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Introduction 

The DOCUMENTER'S WORKBENCH Software is a set of computer pro- 
grams developed at AT&T Bell Laboratories to run under the UNIX operating 
system. These programs help you format any type of document. The 
DOCUMENTER'S WORKBENCH Software supports a range of output devices 
from typewriter-like printers to phototypesetting equipment. 
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Description 



The DOCUMENTER'S WORKBENCH Software is a powerful and sophisti- 
cated set of text formatting tools that helps you produce a wide variety of 
documents, including letters, research papers, memoranda, reports, and 
books. You can use the DOCUMENTER'S WORKBENCH Software to create 
documents that contain tables , mathematical equations, line drawings, and 
plots of data. 

With the DOCUMENTER'S WORKBENCH Software you can dramatically 
diminish the time you need to plan and prepare the following features of 
your document. 

■ margins 

■ tities 

■ lists and displays 

■ footnotes 

■ page headers and footers 

■ page numbering 

■ table of contents 

■ glossary 

■ index 

Anyone can run the DOCUMENTER'S WORKBENCH programs— a clerk, a 
secretary, the writer or editor— you need only a basic familiarity with the 
UNIX operating system. Using any UNIX system text editor, you type in 
your text and intersperse formatting instructions (such as .P for paragraph), 
that state precisely how you want your document to look when it is printed. 
Then you choose the appropriate preprocessors and formatter to process 
your file for printing. 
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Programs 



The DOCUMENTER'S WORKBENCH programs can be grouped into the 
following general categories: 

Formatters nroff and troff are text-formatting programming 

languages for typewriter-like printers and photo- 
typesetters, respectively. These ''super word proces- 
sors" are at the heart of the DOCUMENTER'S WORK- 
BENCH Software. The macro packages and prepro- 
cessors (see below) create instructions that the for- 
matters use to produce a formatted document. 

Macro There are four macro packages available with the 

DOCUMENTER'S WORKBENCH Software: mm, mv, 
man, and mptx. The mm, or Memorandum Macros, 
package allows you to produce memoranda and 
letters easily. The mv package allows you to make 
high quality typeset transparencies in a variety of 
sizes. The man macro package allows you to format 
UNIX system manual pages, and mptx allows you to 
format a permuted index. 

Preprocessors Four preprocessors are included with the 

DOCUMENTER'S WORKBENCH Software: tbl, eqn, 
pic, and grap. tbl helps you make tables: large or 
small, simple or complex, eqn enables you to 
present mathematical notation easily, pic enables 
you to draw a wide variety of forms and line pic- 
tures, and grap, a "language" for describing plots of 
data, automatically scales and labels axes. Preproces- 
sors are used in conjunction with the text formatters 
nroff or troff to produce your final formatted file. 

Programs to Create an Index 

subj scans your document to collect a list of key- 
words, ndx creates an index from the keyword list 
subj makes. 

Programs for Comparing and Checking Documents 

checkmm checks input files and tells you if you 
have made any syntax errors in the DOCUMENTER'S 
WORKBENCH formatting instructions. di£fmk 
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compares two versions of a document and produces 
a third version that highlights the differences 
between the two original files, macref produces a 
cross-reference of the requests, macros, number 
registers, and strings that you use in a file. It is 
helpful for those who want to develop new sets of 
macros. 

Postprocessors daps translates troff output for an Autologic APS-5 

phototypesetter. dilO translates output from troff 
for an Imagen IMPRINT-10 laser printer, tc turns 
troff output into code that a TEKTRONIX 4015 
typesetter can use. 
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Obsolete Programs 



Several programs that were included with Release 1.0 of the 
DOCUMENTER'S WORKBENCH Software are not in Release 2.0. 



checkcw 



checkeq 



dx9700 



mmlint 



non-btLsh 



ocw 



osdd 



is used with ocw, the preprocessor for otroff . It checks 
whether left and right delimiters and .CW/.CN pairs are 
properly balanced. Because otroff is not distributed with 
DOCUMENTER'S WORKBENCH Software 2.0, there is no 
longer a need for checkcw. 

is used with eqn. checkeq is not included in 
DOCUMENTER'S WORKBENCH Release 2.0 because the com- 
mand checkmm provides more extensive checking of proper 
equation formatting. 

prepares troff documents for the Xerox 9700 printer. The 
Xerox 9700 is no longer a supported device, and so the com- 
mand is not distributed with DOCUMENTER'S WORKBENCH 
Release 2.0. 

is a sroff /mm— nro£f/mm document compatibility checker. 
Because sroff /mm is not distributed with DOCUMENTER'S 
WORKBENCH Release 2.0, there is no longer a need for 
mmlint. 

reinstalls mm macros without AT&T Bell Laboratories 
specific features. This command is not included with 
DOCUMENTER'S WORKBENCH Release 2.0 because AT&T Bell 
Laboratories specific strings have been moved to an external 
file called /usr/pub/strings.mm. The system administrator 
can edit this external file to meet local needs. 

is a preprocessor for otroff. Because otroff is not distributed 
with DOCUMENTER'S WORKBENCH Release 2.0, there is no 
longer a need for ocw. 

The osdd adapter macro package is a tool used with the mm 
macro package to prepare Operations Systems Deliverable 
Documentation. The command is not distributed with 
DOCUMENTER'S WORKBENCH Release 2.0. 
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is a postprocessor for otroff . Because otroff is not distri- 
buted with DOCUMENTER'S WORKBENCH Release 2.0, there 
is no longer a need for otc. 

otroff The otroff text formatter is an early version of troff that for- 

mats text for only one device, the C/A/T phototypesetter. 
otroff is not distributed with DOCUMENTER'S WORKBENCH 
Release 2.0. 

sroff sroff formats text for printing on typewriter-like devices and 

line printers, including the Xerox 9700 printer. The Xerox 
9700 is no longer a supported device; therefore, sroff is not 
distributed with DOCUMENTER'S WORKBENCH Release 2.0. 

X9700 prepares nroff documents for the Xerox 9700 printer. The 

Xerox 9700 is no longer a supported device; therefore, the 
command x9700 is not distributed with DOCUMENTER'S 
WORKBENCH Release 2.0. 
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Documentation 



The following documents are available for Release 2.0 of the 
DOCUMENTER'S WORKBENCH Software system: 

■ UNIX System V DOCUMENTER'S WORKBENCH Software User's 
Guide (Select Code 310-004): The User's Guide contains three 
sections: 1) the "Sampler/' which shows files before and after 
formatting, 2) a preface, and 3) tutorials. The first two sec- 
tions familiarize the novice with the software in general, and 
the tutorials cover its use in detail, 

■ UNIX System V DOCUMENTER'S WORKBENCH Software Technical 
Discussion and Reference Manual (Select Code 310-005): Organ- 
ized to suit the more experienced user, this technical explana- 
tion of the software is presented according to patterns of cus- 
tomary use. The components of the software are discussed in 
detail, and manual pages are also provided. 

■ UNIX System V DOCUMENTER'S WORKBENCH Software Handbook 
(Select Code 310-008): The Handbook is a memory jogger for 
accomplished users who want a more technical understanding 
of the software. 

■ UNIX System V DOCUMENTER'S WORKBENCH Software Handbook 
for New Users (Select Code 310-009): This handbook is aimed 
at new users. It is task-oriented, and it incorporates aspects of 
the "Sampler" from the User's Guide, 

■ UNIX System V DOCUMENTER'S WORKBENCH Software Product 
Overview (Select Code 310-006): This document provides a 
summary of the software and its features, a list of available 
documents, and a brief technical description for those who 
might be asked to evaluate the software. 

■ UNIX System V DOCUMENTER'S WORKBENCH Software Release 
Notes (Select Code 310-007): The Release Notes, written for 
system administrators, includes the software installation pro- 
cedures for all processors that support the DOCUMENTER'S 
WORKBENCH Software. In addition, it gives transition infor- 
mation for owners of earlier product releases. 
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You may get copies of the documents in this list from AT&T. When 
placing orders, refer to the Select Code for the document that you want (for 
example 310-004 for the User's Guide), 

write to: AT&T Customer Information Center 

P.O.Box 19901 
Indianapolis, Indiana 46219 

or call: 1-800-432-6600 within the continental United States 

To order the DOCUMENTER'S WORKBENCH Software Release 2.0 call 
1-800-828-UNIX for the source product 

1-800-247-1212 for the binary product 
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Supported Hardware 

The following list identifies the hardware on which DOCUMENTER'S 
WORKBENCH Release 2.0 is supported for UNIX System V Release 2.0 as of 
April 1985: 

■ AT&T 3B2/300,400 Computers 

■ AT&T 3B5 Computer 

■ AT&T 3B20S/A Computers 

■ VAX 750 

The UNIX operating system and components of the DOCUMENTER'S 
WORKBENCH Software have been run on various other computers, includ- 
ing DEC PDP-11/45, PDP-11/70, and VAX-U/780 mini-computers. 

Specifications for the 3B20 Computer and the VAX 

For the AT&T 3B20 Computer and the DEC VAX-1 1/780 and VAX-1 1/750 
computers, the source code for the DOCUMENTER'S WORKBENCH Software 
Release 2.0 is distributed on a single magnetic tape containing two files in 
epic format, written at 1600 bpi. Only a system administrator with root 
privileges may access this tape. Installing the object code of DOCUMENTER'S 
WORKBENCH Software Release 2.0 also requires root userid privileges. The 
Release Notes (310-007) presents complete installation instructions. 



Specifications for the 3B5 Computer 

For the 3B5 Computer, source code is distributed on either a Lark II disk 
cartridge or a nine-track magnetic tape, and contains two files in epic for- 
mat. (The binary version of the DOCUMENTER'S WORKBENCH is only avail- 
able on nine-track magnetic tape.) Again, it is written at 1600 bpi, and root 
userid privileges are required. The Release Notes (310-007) presents com- 
plete installation instructions. 



PRODUCT OVERVIEW 9 



Overview of Technical Information 



Specifications for the 3B2 Computer 

Installing the DOCUMENTER'S WORKBENCH Software on the 3B2 Com- 
puter requires four floppy disks. Each floppy disk contains "install" and 
"uninstair scripts for the installation and removal of the files contained on 
it. The required disk space for this product is 5500 blocks in the /usr file 
system. 

The first floppy disk contains all files that you need to use troff, grap, 
mmt, mvt, pic, eqn and tc plus a driver (for the Autologic APS-5 typesetter) 
and the font tables for this driver. The files on this first disk require 1100 
blocks (512 bytes/block) of free space in the /usr file system. 

The second floppy disk contains all the files you need to use nroff, 
neqn, mm, and man. The files on this disk require 750 blocks of free space 
in the /usr file system. 

The third floppy disk contains files used by both nroff and troff . This 
disk requires 1300 blocks of free space in the /usr file system. 

The fourth floppy disk contains the driver, font tables and raster tables 
for the Imagen IMPRINT-10 laser printer. The files on this disk require 
2350 blocks of free space in the /usr file system. 

You can find a detailed list of the files on each floppy together with 
complete instructions for installation in the Release Notes, 



Terminal Dependencies 

You can display text processed by nroff, tbl, neqn and mm on a 
typewriter-like printer or on a terminal without graphics capabilities. Text 
processed by troff, the mv macro package, eqn, pic, and grap must be sent 
to a terminal or a printer that supports typesetting (for example, a Teletype 
5620 terminal). 



Software Dependencies 

AT&T supports the DOCUMENTER'S WORKBENCH Software Release 2.0 
only on UNIX System V Release 2.0 and subsequent releases. AT&T does 
not support DOCUMENTER'S WORKBENCH Software Release 2.0 on any other 
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version of the UNIX system. All the software that the DOCUMENTER'S 
WORKBENCH Software needs for installation and execution is part of UNIX 
System V Release 2.0 and subsequent releases. 

On AT&T 3B2 Computers, the following utilities packages must be 
installed before the DOCUMENTER'S WORKBENCH Software can be installed: 

Directory and File Management Utilities Package 

Terminal Filter Utilities Package (must be purchased separately) 

The installation script checks that these packages are installed on your 
3B2 Computer and will prevent you from installing the DOCUMENTER'S 
WORKBENCH Software if they are not installed. 
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Introduction 



The DOCUMENTER'S WORKBENCH programs provide tools of unusual 
precision for arranging and modifying text. The family of programs 
included in the workbench allows you considerable control over text and a 
wide range of functions. Without going through a maze of menus, you are 
offered a large collection of text formatting commands that will help you 
draft and revise text. You can also define and name your own formatting 
commands using conventions any beginner can quickly master. 

You can make your own shapes, characters, pictures, figures, and form 
memos and letters and store them to be quickly and easily used for other 
tasks. Most important, the DOCUMENTER'S WORKBENCH programs are an 
integral part of the UNIX operating system, which allows you to write a sin- 
gle script to edit several files at once, check spelling, analyze your writing 
style, communicate with other computers, and develop your own tools for 
sophisticated text processing. On the other hand, if you only need a few 
tools for writing simple memos and other uncomplicated text processing 
tasks, you can use the programs that way, too. 

A few of the DOCUMENTER'S WORKBENCH system's tools are tbl, pic, 
and eqn. The table-drawing tool, tbl. 



makes all sorts of tables. 


and 


what 


is 


best 


about 


tbl 


is 


that 


once 


you 


make 


a 


table 


you 


like. 



you can save it for later use. 

The picture drawing tool, pic, allows 
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eqn, the tool for preparing equations, enables you to present accurate 
mathematical notation: 

i-0 ^ 

These tools are sensible and comfortable to use. The mathematical nota- 
tion given above, for example, was produced from this input: 

sum f ran i=0 to infinity x sub i = pi ower 2 

eqn allows you to describe equations as you would describe them to another 
person. You will find that a brief exposure to the eqn language will enable 
you to use it without referring to the tutorial. 

Following a first draft, you can revise your copy with tools such as 
diffmk and hyphen, and you can check the formatting requests you have 
used with checkmm. When you have completed your document, you can 
compile a table of contents and an index. 
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Formatting Commands 



To use the DOCUMENTER'S WORKBENCH programs, you need only know 
a few basic concepts. The primary ones you can guess by looking at the 
Sampler. Unlike a simple text processor, the DOCUMENTER'S WORKBENCH 
programs enable you to specify to a fine degree precisely what you want. 
You type in your text and intersperse formatting commands that state how 
you'd like your document to look. One glance at the Sampler shows the 
obvious difference between text lines and formatting commands (control 
lines). But it is worth emphasizing: control lines begin with a dot (.), and 
the dot must occupy the leftmost position on the line. Only control lines 
can begin with a dot because it tells the computer that what follows on the 
line is not text to be printed, but a formatting command. 

There are two types of formatting commands; requests and macros. 
You will learn more about these as you read the tutorials. For now, you 
only need to know two things about them. 

First, most request names are one or two lower-case letters, and most 
macro names are one or two upper-case letters. Both requests and macros, 
of course, are lines that begin with a dot. 

Second, both requests and macros are "open to argument." That is, if 
you don't like the way they behave (or rather, make your text behave), you 
can change them. For example, somewhere in your text you need more 
than the one blank line that you get with the .sp request. You can make 
this happen by following the .sp request with an argument. If you need 
three and a half blank lines, you would follow the .sp with a single space 
and then an argument: 

These lines are separated by 
• sp 3.5 

three and a half spaces. 
The formatted version of these three input lines would look like this: 
These lines are separated by 



three and a half spaces. 
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Similarly, you can give a macro an argument. If you want a display of 
text centered in the middle of normal text, you would use the display macro 
•DS and follow it with the centering argument, C. Typing 

.DS C 

liiis teact is centered. 
.DE 

will give you this: 

This text is centered. 

•DS and .sp will accept other arguments as well, effectively multiplying the 
number of fine-tuning knobs at your disposal. 

Requests and macros can be followed by comments, which are fre- 
quently used as reminders. Like a request or macro, a comment does not 
appear in output. Here's how they look: 




.if n .sp 3.5 \" if nroff is the fomatter, give ite three and a half inches 
•if t .sp 1.75 \" bat if troff is the formatter, I'd like half that mich 




The only things separating the request from the comment are spaces 
and the string \". Because the line begins with a dot, we don't need one 
preceding the \" string. The comment will be protected from machine 
interpretation all the same. Do not separate comments from requests with a 
tab; only spaces will be recognized as valid request or argument delimiters. 

One additional formatting command will complete a basic knowledge of 
the DOCUMENTER'S WORKBENCH language: the escape sequence (so-called 
because it always includes the escape character, or backslash: \). Like 
requests and macros, an escape sequence controls all text that follows it, and 
some require arguments. The differences between an escape sequence and 
requests and macros are that an escape sequence does not appear on a line 
that begins with a dot, and no space intervenes between it and its argu- 
ments. 
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The escape sequence's advantage over the other formatting commands is 
its ability to get into tight places. If you want to change a single word or 
just one character without affecting anything else on a line, you can target 
just that word or character by preceding it with an escape sequence. Let's 
say you want to print a sentence using a bold font, but one word in the sen- 
tence needs to be in italic. You can do this by using the escape sequence 
together with requests and macros. You would type the following: 

.ft B 

aSiese are bold words with an \fIitalic\fB word ancsng them, 
.ft R 

The printed results would look like this: 

These are bold words with an italic word among them. 

That is, after you used the font request (.ft) and its argument for bold (B), 
you can make an exception to bold by using the font escape sequence (\f ) 
and its argument for italic typeface (I). 

If you have special formatting requirements that the standard library of 
requests, macros, and escape sequences cannot satisfy, you can fashion your 
own macros and escape sequences and save them for later use. As you will 
see later in this tutorial, the conventions for doing this are easy to learn and 
use. 
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To this point you have seen before and after versions of files: the ones 
you type in and the ones you see come out in print. These two versions, as 
you may know, are called input and output. An important effect of process- 
ing (what happens to your input on its way to becoming output) is that the 
number of lines you get out is not always the same as the number you 
typed in. You know, for example, that all the control lines will disappear 
and that the spaces they once occupied will vanish. The escape sequences 
(and the spaces they once occupied) also will disappear when your input is 
processed. Similarly, the text in your input file will be formatted, line by 
line, from left to right, according to the format you specified. 

This activity of filling the page with formatted text is called line filling. 
That is, a line will start filling from the left-hand margin and will continue 
until it gets to the right-hand margin where it will drop to the next line at 
the left margin, and so forth. When each line reaches the right-hand mar- 
gin a number of things will be done, depending on your instructions. The 
right-hand margin will be aligned (adjustment) unless you ask for non- 
adjustment (.na). Words will be hyphenated according to rules you specify, 
or will not be hyphenated if that's what you want. 

The practical point to be made about line filling is that you can turn it 
off or on with the requests .fi (fill) and .nf (no fill). If you would like to set 
up columns (or any other configuration of words for that matter) and have 
them come out exactly as you typed them in, you can request no fill mode. 

For example, if you processed the following file: 




.nf 



'Shese are 
words that 
maJce short 




the output would look like this: 
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These are 
words that 
make short 
lines of input. 

Using the fill request, however, would cause the formatter to automatically 
fill each line with as many words as will fit on it. Here is the contents of 
the input file: 



r 




.fi 



Ihese are 
wsrds that 
nialce sfaort 




lines of iiqwit. 



And now the formatted output: 



These are words that make short lines of input. 
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Once you are ready to process your input files, you name the tools you 
used and your file or files, and the UNIX system will prepare them and send 
them to a printer. If you are preparing correspondence-quality text, you 
would be working with nroff (pronounced EN-ro£f) requests and escape 
sequences. If you were also using the mm (memorandum macros) macros, 
you would need to tell nroff that you had used them. The line you would 
type looks like this: 

nroff —mm my .file 

This is called a command line. The minus sign (-) tells the system that 
mm is a macro package it must use when it processes my.file. The system 
will then consult nroff and mm to fulfill the requests, macros, and escape 
sequences in your text. Once your files have been processed, you will have 
two versions: input and output. Processing never affects your original input 
file. 

The output of files that are processed with mm or nroff can be sent to 
any printer. This is also known as piping the output to a printer, and is 
indicated in the command line by a vertical bar ( | ) between the command 
that formats the input file and the name of the printer. 

nroff —mm my.file | printer 

After entering this command line, your formatted copy will be output on 
the printer. 

The files that are processed with mmt or troff are piped to a typesetter: 

troff —mm my .file | typesetter 

Only devices capable of producing typographical copy— phototypesetters, 
laser printers, or sophisticated dot-matrix printers— may be used to produce 
troff output. 

The command line should reflect the formatting commands in your file. 
If you use requests that are unique to troff in your file, you must name troff 
in the command line. Think of the command line as a declaration of the 
activity in each file. The rules for how you make that declaration are loose 
in some cases and rigid in others. Each tutorial will list the appropriate 
command lines to process your text. The following table shows a selection 
of command lines to give you a feel for the rules. 
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Command Lines 




Tools used 


Customary syntax 


Alternative syntax 


mm macros 


nro££ —mm file 


mm file 


nroff 


nroff file 


none 




nroH and mm 


nroff —mm file 


mm file 


neqn, nro£f and mm 


neqn file \ nroff —mm 


mm - 


-e file 


neqn, nroH, tbl and mm 


tbl file 1 neqn| nroff -mm 


mm - 


-e file 


troff and mm 


troff -mm file 


mmt 


file 


tbl, nroH, and mm 


tbl file 1 nroff —mm 


mm - 


-t file 


pic, itoH, and mm 


pic file 1 troff -mm 


mmt 


-pfile 


eqn, pic, tro£f, and mm 


pic file 1 eqn | troff -mm 


mmt 


— e — p file 


tbl, eqn, pic, tro££ and mm 


pic file 1 tbl 1 eqn | troff -mm 


mmt 


-e — p — t file 


grap, trotf, and mm 


grap file \ pic | troff -mm 


mmt 


-Zfile 
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The following notes may help you avoid problems or to troubleshoot 
when problems do occur. 

■ The checkmm command will flag some business letter macros as 
possible errors, even though a file containing the letter macros 
will format properly. 

■ The checkmm command will flag as possible errors the macros 
that produce labeled footnotes, if they occur inside lists. A file 
containing such a sequence of macros will format properly, 
however. 

■ The chapter "The Preprocessor eqn" in the Use/s Guide suggests 
running the eqn preprocessor on the 

/usr/lib/dwb/samples/eqn.stats file. If you do this you will 
get the following warning: 

eqpi warning: unquoted troff ocnmand 

The file eqn.stats will format properly, however. 

■ A README file is supplied with the binary version of the 
DOCUMENTER'S WORKBENCH Software for the 3B5 Computer 
and the 3B2 Computer. This file incorrectly states that there are 
only three macro packages included in the package, although it 
correctly names the four packages that are included: mm, mv, 
mptx, and man. 

■ Use of the mv macro package inhibits true constant width spac- 
ing in the output text. If you need to show constant width spac- 
ing in a viewgraph you can simulate it by entering the troff 
request 

.ss 12 

before the text you want to appear in constant width spacing. 
From that point, standard troff inter-word spacing will be used. 
You can restore the standard mv inter-word spacing by entering 
the request 

• ss 16 

at the point you want it to resume. 
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The DOCUMENTER'S WORKBENCH Software 
Sampler 



The variety of text processing that the DOCUMENTER'S WORKBENCH 
Software offers can be seen in the samples that appear in the following 
pages. The input files shown in screens are those you type at the terminal. 
Each input file is named, and the command you would use to process each 
is given after its screen. On the facing page is the processed file: the ver- 
sion you would get from your printer or phototypesetter. 



NCJIH 



The examples of output in this sampler were processed for a standard 
8.5xll-inch page and have been photo-reduced to fit on the 6.25x8.5-inch 
pages of this guide. As a result, the type sizes in the output examples will 
not correspond to the formatting instructions shown in the input examples. 



The input files are in /usr/lib/dwb/samples. You can copy any of the 
files into your own directory to use as the basis for your text processing 
activities. For example, the following sequence of commands copies the 
first sample, nroff.letter, into the directory /usr/yourlogin. 

$cd /usr/yourlogin <RETURN> 

$cp /usr/lib/dwb/samples/nroff.letter nroff Jetter <RETURN> 

Many printers are capable of producing most of these samples. Begin- 
ning with the eqn.stats file, however, producing the sample outputs will 
require sophisticated printers or phototypesetters that have multiple fonts 
and graphics capabilities. Because of the wide variety of printers, the com- 
mands that follow the screens of input do not name any specifically. You 
will have to check with your system administrator to determine the printers 
(and printer names) available on your system. 

If you want to read more about the formatting commands used in the 
Sampler, refer to the alphabetical request index or summary beginning The 
nroff/troff Technical Discussion" in the Technical Discussion and Reference 
Manual. Some of these samples also appear in the Handbook for New Users, 
which gives more detail about the function of each macro or request in the 
input files. 
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File: nroff.Ietter 



.in -i-O.Si 
October 14, 1984 
.sp 2 
.nf 

John 9aaith 

Business Qaspater Systems, mc. 
190 River Bculevazd 
Durliam, NC 27707 
•sp 2 

Dear Mr. Sooith: 

•sp 2 

.fi 

I would like to be considered for the positian of Docunsnt Production Coordinator 
with Business Ooqputer Systems, Inc. 

I have a B.A. in E^lish and have finished course wark for a ^bsters in Qiglish. 
Ourrently, I am assisting Steve Ebley, Production Editor with Techno-Publishing 
in Jonesvllle. 

My duties consist of proofreading documents and ooordinating graphics pro du ctio n , 
.sp 

While I enjoy my position here, I knew I am ready for more challenging work and 
greater responsibility. 

Our shop uses a oonputer running ixnx. System V. 

I am confident in my potential for growth with the Technical Writing Staff 
at Business Oonputer Systems. 

I have enclosed my resume and two letters of reocniaendation. 

Please feel free to contact my present sapervisor %dth any questions you may hove. 

I am acvailable for an interview at any time, and I lock for\4ard to hearing from 

you. 

.sp 2 

.nf 

Sincerely yours, 
.sp 5 

John Jdies 
41 Stanford Drive 
Bridgewater, NJ 08807 
•sp 2 

Enclosures: 3 



Command line: nroff nroff Jetter | printer 
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October 14, 1984 



John Smith 

Business Computer Systems, Inc. 
190 River Boulevard 
Durham, NC 27707 



Dear Mr. Smith: 



I would like to be considered for the position of Document 
Production Coordinator with Business Computer Systems, Inc. 
I have a B.A. in English and have finished course work for a 
Masters in English. Currently, I am assisting Steve Foley, 
Production Editor with Techno-Publishing in Jonesville. My 
duties consist of proofreading documents and coordinating 
graphics production. 

While I enjoy my position here, I know I am ready for more 
challenging work and greater responsibility. Our shop uses 
a computer running UNIX System V. I am confident in my 
potential for growth with the Technical Writing Staff at 
Business Computer Systems. I have enclosed my resume and 
two letters of recommendation. Please feel free to contact 
my present supervisor with any questions you may have. I am 
available for an interview at any time, and I look forward 
to hearing from you. 



Sincerely yours. 



John Jones 

41 Stanford Drive 

Bridgewater, NJ 08807 



Enclosures; 3 
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File: mm.report 




Vfork Pzx>gxes8 Peport — Seocoid Quarter 1984 

.AF "Business Occpxter Systems, Inc." 

.AD "W. Willianis" W XF 665414 5398 7-123 baileylwww 

,m 

.HU "Writing Assignments" 
.P 

I started work with the Tedmioal Writing Staff on April 16. 

H/ writing assigments are: 

.BL 

.U 

Documentaticn for the DCS Fortran ocnpiler 

.DL 

.LI 

I oollected materials relevant to inplementing programming languages 
on the UNIX* 
.FS « 

Trademark of /OS^ 
.FE 

system. 

.LB 

.LI 

Documentaticn for the Distributed Transaction Processing system (DTPS) 2.0 

.DL 

.LI 

I reviewed DTPS requirements, outstanding ocirplaints about DTPS, and users' 

suggestions for improving OTPS dcxninentatian. 

.LE 

.LE 

.HU "Other Activities" 
.P 

On JUne 16, I went to a oonference, "Writing About Oonpiters," at Acme State 
Oollege. 

^ y 

Command line: mm -Tip mm.report | printer 
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Business Computer 



Systems, Inc. 



subject: Work Progress Report — 
Second Quarter 1984 



date: December 4, 



1985 



from: W. Williams 



XF 665414 
7-123 X5398 
bailey ! www 



Writing Assignments 

I started work with the Technical Writing Staff on April 16. 
My writing assignments are: 

m Documentation for the BCS Fortran compiler 

- I collected materials relevant to implementing 
programming languages on the UNIX* system. 

© Documentation for the Distributed Transaction 
Processing System (DTPS) 2.0 

- I reviewed DTPS requirements, outstanding 
complaints about DTPS, and users' suggestions for 
improving DTPS documentation. 

Other Activities 

On June 16, I went to a conference, "Writing About 
Computers," at Acme State College. 



W. Williams 



* Trademark of AT&T 
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File: mm.sales 



.ds HF 3 3 3 3 
.ND "October 30, 1984" 
.TL 

New York Sales Assignnents 
.AU "A. B. Sttdth" 

.AF "Business Oocqputer Systems, Inc." 

.MP "EKOPOSAL" 

.P 

Fending your approval, here are the sales assignments for New York £or 1985. 

.HU "New York" 

.D6 

.TS 

box tab{ ; ) ; 
1 1. 

district; sales representative 

Haxihattan; S&dth 
Westchester ; Snaith 
Albaxx7;Roberts 
Syracuse; Smith 
Bu£falo;ltoberts 
,TE 

.SG 

.AV "John Jdhnscn: Director" 
.NS 

B. Roberts 
.NE 



Command line: mm -t -Tip mm.sales | printer 
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Business Computer Systems, Inc. 

subject: New York Sales Assignments date: October 30, 1984 

from: A. B, Smith 

PROPOSAL 



Pending your approval, here are the sales assignments for 
New York for 1985. 

New York 



Idistrict 


sales representative 1 


1 Manhattan 


Smith 1 


1 Westchester 


Smith 1 


1 Albany 


Roberts 1 


1 Syracuse 


Smith 1 


1 Buffalo 

1 


Roberts 1 



A, B. Smith 

APPROVED: 



John Johnson: Director Date 

Copy to 
B. Roberts 
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File: mm.letter 



.LO AT "Research Staff" 

.WA "James Locrin, Ph.D." "Director of Pesearch" 

Business Ocnputer systems. Inc. 

190 River Boulevard 

Durham, N.C. 27707 

.WE 

.LO SA "Dear Dr. anith:" 
.LO CN 

.lA "Eced Stadth, Ph.D." 

Golunibia lAiiversity 

116th Street 

Nfew York, NY 10019 

.IE 

.LO SJ "Suamit Research Project" 

.LT BL 

,P 

Ohe eoqperiements are almost ocnplete. 

We hope to finish v;^ work in this area soon. 

rOie first publication has been cleared by Steve. 

I have a lr ea dy sent it to several journals. 

I expect to hear from them soon if the paper needs 

revisions. 

.P 

We appireciate all the help you have given us. 

We look forward to collaborating with you again. 

.FC "Sincerely," 

.SG JL-der 

.NS 5 

.NE 

.N5 

J. Brown 
.NE 



Command line: mm -Tip mm.letter | printer 
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Business Computer Systems, Inc. 
190 River Boulevard 
Durham, N.C, 27707 
December 4, 1985 

CONFIDENTIAL 



Fred Smith, Ph.D. 
Columbia University 
116th Street 
New York, NY 10019 

ATTENTION: Research Staff 

Dear Dr. Smith: 

SUBJECT: Summit Research Project 

The experiements are almost complete. We hope to finish up 
work in this area soon. The first publication has been 
cleared by Steve. I have already sent it to several 
journals. I expect to hear from them soon if the paper 
needs revisions. 

We appreciate all the help you have given us. We look 
forward to collaborating with you again. 



Sincerely, 



James Lorrin, Ph.D. 
Director of Research 

JL-der 
Enc. 
Copy to 
J . Brown 
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File: tbLlanguage 



r 




.TS 



bOKyCenter; 
c c c 
111. 

Iaxiguage<»s>Ajtliors<nB>nriinaxy Use 

AFL<nffl>I£M<nffi>Mathaiatics, A{plicaticBis 
Basic<TAB>DcurbiDuth<TAB>ateachii^ Applications 
C<TAS>HIT«<UB>Stystenis, i^licaticns 
OG!B0L<TAB>tteuny<TAB>Busi2iess ^Applications 
F3rtran<TAB>l&nyr<i»B>Scienti£ic i^pplicaticns 
LISP<MB>M.I.T.<MB>Artificial Intelligence 
Ba8Gal<i»B>Stanfard<nB>TeaGhingr, Systans 
Hi/1<aia>im<»s>iApplicatiGns 
SN0QOI4<Tiffi>AIST<nffl>i)|]pliGatiGns 



Command line: tbl -TX tbLlanguage | nroff -mm -Tip | col | iprinier 
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1 Language 

1 

1 


Authors 


Primary Use 1 


lAPL 

iBasic 

IC 

1 COBOL 
1 Fortran 
ILISP 
1 Pascal 
lPL/1 
1 SN0B0L4 
1 


IBM 

Dartmouth 

BTL 

Many 

Many 

M.I.T. 

Stanford 

IBM 

AT&T 


Mathematics, Applications 1 
Teaching, Applications 1 
Systems, Applications 1 
Business Applications 1 
Scientific Applications 1 
Artificial Intelligence 1 
Teaching, Systems 1 
Applications 1 
Applications 1 
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.TS 
boK^centGTt 

CSS 

c I c l*c 
1 I 1 I n. 

Major New York Bridges 

Bridge<TAB>Desi9ner<»B>Length 

hcocaOyn<ua>J , A. Roebliiig<WBP^1595 
Mahhattan<M8>G. Li2]deathal<iMB^1470 
ULlllainsburg<»B>L. L. Buck<nB>1600 

aieensb09xu9li<BMB>BaliQer &<mB>1182 
<TAB> Hocnbostel 

<iMB><nB>1360 

Tt^ibaEcuig^<TAB>0. H. itaiaxin<nB>_ 

<1»B><TAB>383 

Broonc VZhitestcne<aMB>0. H. A3iDann<TAB>2300 
fOirogs Nedc<TAB>0. H. Aiiinann<i»B>1800 
.TE 



Command line: mm -t -Tip tbLbridges \printer 
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1 Major 


New York Bridges 




1 Bridge 


1 Designer 


Length 


1 Brooklyn 
■Manhattan 
1 Williamsburg 


1 J. A. Roebling 
1 G. Lindenthal 
1 L. L. Buck 


1595 
1470 
1 1600 


1 Queensborough 


1 Palmer & 

1 Hornbostel 


i 1182 


1 Tri borough 


1 0. H, Ammann 


1 1380 

1 383 


1 Bronx Whitestone 1 0* H. Ammann 
iThrogs Neck 1 0. H* Ammann 


1 2300 
1 1800 
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.TS 

center box tab( ; ) ; 
c s s 8 s 
c { c ! 1 ! 1 I 1 
1 I 1 I 1 I 1 I 1. 
itoerican Presidents 

s 

Naii«;Baarty;Tem;Electitm<)pixxts;Not^ 
T{ 

Gerald 
R. Ford 

T};Republlcan;1974-1977;Never elected;T{ 
Became V.P. 
Agnew resigned 
T) 



T{ 

Jinny 
Carter 

T} ;Denioci:atic; 1977-1981 ; 1976-Etard;T{ 

Negotiated 

Cetnp David 

treaties 

T} 

T{ 

Ronald 
Reagan 

T} ;Republican; 1981-;T{ 
1980-Carter 

Anderson 
1984-Mondale 
T};T{ 
Oldest 
President 
T} 




Command line: mm -t -Tip tbLpres | printer 
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I American Presidents 



1 Name 
1 


j Party 


Term 




Elect ion-Oppnts 


Notes 


1 Gerald R. 

iFord 

1 

1 


1 Republican 

1 
1 


1974- 


1977 


Never elected 


Became 
V.P, when 
Agnev 
resigned 


IJimmy 
1 Carter 
1 
1 


1 Democratic 

1 

1 

1 


1977- 


1981 


1 1976-Pord 


Negotiated 
1 Camp David 
1 treaties 


1 Ronald 
j Reagan 


1 Republican 


1 1981- 

1 

1 




1 1980-Carter 
1 Anderson 
1 1984-Mondale 


1 Oldest 
1 President 
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File: eqn.stats 



.H 1 ''Measures of Central TendoKy: Hean, Median and Mode" 
.P 

The mean is the aritlinetic average for a set of soGores. 
The fonmla for CGnpiting a mean (M) is 
•BP 2 
.D6 

.m 

M {sum from {i-=-1} to n {x sub i} } over n 



.P 

HhB median divides ranked scores into halves. 
Given that the \f anedian lnterval\fP 

is the soore interval that contains the n/2nd largest score when scores 

are ordered by size» the fomila for cociiuting a median (Md) is 

.sp 4 

.DS 

.BQ 

Md left ( pile {lower-real above limit-of above median-interval} 
ri^t ) 
+ 

left ( pile {%fidth-of above median above interval} 
ri^ ) 
left [ 

{(n / 2) - left ( pile {Cumilative 

above frequencyn^jN to 
above the -median- interval} 

rig^it )} 

over { pile {frequency-in above median-interval} } 
rl^ ] 



,P 

ilhe mode is the most frecjuently occurring soore in a gioiq> of scores. 



Command line: eqn eqn.stat8 1 tro£f —mm | typesetter 
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/. Measures of Central Tendency: Mean, Median and Mode 

The mean is the arithmetic average For a set of scores. The formula for computing a mean (M) is 



n 

n 

The median divides ranked scores into halves. Given that the median interval is the score interval 
that contains the n/2nd largest score when scores are ordered by size, the formula for computing a 
median (Md) is 



Md - 



Lower real 
limit of 
median interval 





width of 


+ 


median 




. interval j 



(n/2)- 



Cumulative 
frequency up to 
the median interval 



frequency in 
median interval 



The mode is the most frequently occurring score in a group of scores. 
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File: troff.sizes 



•rs 
.sp 4 

\s3ei3ie Size \s10o£ chazacters is useful for ensphasis 

or for meeting special reading needs such as making posters or aiding those 
with poor eyesi^t. 

Hie range of Nflpoint sizesNfR at a \fItroff\fR user's disposal is potentially 
quite broad. 

'Ote actual limits in each case, though, are iiqposed by the individual printer 
si:qpporting a IJNIX system. 

Like oontrol of typeface, or font, yoa can ocsitzol size both before and in the 
middle of a line. 

The modification of character size also requires that we keep an eye en the size 
of vertical space between lines of text. 

\fItroff\fR, characteristically, puts the control in your hands: 
.sp 1 
.ps 12 
.vs 14 

Ihis request is for a point size of 12 and should be followed by a verUcal 
space of 14. 
.ps 14 
.vs 16 

A jiBp to 14, thcoc^, is quite a bit larger. Ohat means our text will lode best 
with a vertical space of 16. 

\fI.vs\fR enables yew to space these lines of large type wittoit fear of 
overlapping characters, 
.ps 22 
.vs 24 

We can also change size on a word-by-word basis like this: 
Whether ycu want \s10ten \s12twelve \s14fourteen \s16sixteen or \s20twenty, 
an in-line ocQnend will do anything a before-the-line ccnnand will do. 
\s10Don't forget to return to ten point unless you want all the rest of your 
.text in twenty point. 



Command line: troff tro£f.sizes | typesetter 
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The Size of characters is useful for emphasis or for meeting specia! reading needs 

such as making posters or aiding those with poor eyesight. The range of point sizes at a trqff user's disposal 
is potentially quite broad. The actual limits in each case, though, are imposed by the individual printer 
supporting a UNIX system. Like control of typeface, or font, you can control size both before and in the 
middle of a line. The modification of character size also requires that we keep an eye on the size of vertical 
space between lines of text, troff, characteristically, puts the control in your hands: 

This request is for a point size of 12 and should be followed by a vertical space of 14. A 
jump to 14, though, is quite a bit larger. That means our text will look best 
with a vertical space of 16. .vs enables you to space these lines of large type 

without fear of overlapping characters. We can also change 

size on a word-by-word basis like this: Whether 
you want ten twelve fourteen sixteen or twenty, an in-line 
command will do anything a before-the-line command 

will do. Don'l forget to return to ten point unless you want all the rest of your text in twenty point. 
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.sp 4 
.ps 14 
.vs 16 
.Is 2 
.P 

Hcwever sophisticated ycur printer is, \fItroff\fR can probably handle your fcnt 
control. 

By placing .ft cn a line by itself before the line of text you want to change 

or \f before the ward or words you want to change, you can modify your t^^pography. 

.ft I 

Ihis is a line of italic node with .ft I (italic). 

.br 

.ft B 

If you prefer a heavier enjAasis, use bold rorran type nade with .ft B (bold). 

.br 

.ft H 

For the clean appearance of a sans serif type, iise .ft H (Helvetica). 

.br 

.ft R 

Pcman is the roost popular, of course. 
.P 

The \f allows for a finer level of control: 

Ihe individual \fIitalic\fR, \fBbold\fR, or \fHHelvetica\fR word can be done 

in-line. 

.P 

All printers were not created equal, so consult your systems manager to find vtot 
is available, 
.ps 10 



.vs 12 





Command line: troff -mm troff.fonts | typesetter 
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However sophisticated your printer is, troff can probably handle your 
font control. By placing .ft on a line by itself before the line of text 
you want to change or \f before the word or words you want to change, 
you can modify your typography. This is a line of italic made with .ft 
I (italic). 

If you prefer a heavier emphasis, use bold roman type made with .ft B 
(bold). 

For the clean appearance of a sans serif type, use .ft H (Helvetica). 
Roman is the most popular, of course. 

The \f allows for a finer level of control: The individual italic, bold, or 
Helvetica word can be done in-line. 

All printers were not created equal, so consult your systems manager to 
find what is available. 
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File: troff.ad 



r 

.rs 




.sp 2 
.ce 11 
.ft B 
.ps 24 

Growing Oonpiter Software Oonipary See}&<3 

.sp 4 

.fp 4 GS 

.ft GS 

esqperienced 

•Sp 2 

\s26C Progranroer 
.sp 5 
.fp 4 S 
.ft B 

\s24lQncwledge of 
.vs 30 
,ps +1 

\fHUNIX System \^fP 

.ps -1 

A Must 

.vs 

.sp 5 

O ppor tunity For \fIBapid\fB Advancenent 
.sp 6 
.ps 24 

\v'-0.2i'Ut)\v'+0.2i'beat Wbrking Erxvironnient 
.sp 4 

\s20Call 012-345-6789 
.sp 2 



.sp 2 

Lo\h'-0,33m'ok In These Pages Fbr Further mfoonation 
.ft R 



Command line: troff troff.ad | typesetter 
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Growing Computer Software Company Seeks 

© ^Programmer 

Knowledge of 
UNIX System V 
A Must 

Opportunity For Rapid Advancement 

T Tn 

^beat Working Environment 

Call 012-345-6789 
or 

L«»k In These Pages For Further Information 
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File: troff.aeneid 



.in 1.2i 
.sp 3 
.ps 36 
.ce 1 

}\h'-0.an'{}Nai'-0.5in'{}\h'-0.5m'{}\h'-0.5mM)Nh'-0.5m'{}\h'-0.^ 

Nai'-0.5m'{}\h'-0.5m'{}\h'-0.5m'{}\h'-0.5m'{}\h'-0.5mM}\h'-0.5m^ 

W -0 . 5m' { }\h' -0 . 5ra' { }\h' -0 . an' { )\h' -0 . 5mM }Nh' -0 . 5m' { }\h' -0 . 5m' { 

\h'-0.&n'{}\h'-0.5m'{}\h'-0.5m'{}Nai'-0.5m'{>\h'-0.5m'{}\h'-0.5m'{}\^^ 

\h'-0 . an' { }\h' -0 . 5m' { >\h'-0 . 5m' { }\h'-0 . Sm' { }\h' -0 . 5m' { }\h' -0 . 5m' { }\h'-0 . 5m' { }\ 

\h'-0 . 5m' { }\h' -0 . 5m' { } W -0 . 5m' { }\h'-0 . 5m' { }\h' -0 . an' { }NJi' -0 . 5m' { }\h'-0 . ^ 

.sp 2 

.ce 3 

.1 "\S24'I11E ARGCMESTTES OF" 
.Sp 1 

.1 "\s22the thirteene booikes of Aeneidos/' 
•Sp 2 

.B "Nslleaqpressed in verse." 

.sp 3 

.Is 2 

.nf 

.ps 6 

.m 1 5 

.ps 10 

.hr 

.B 

1. AEMEAS, \f2in the \(first, to \f3Lyty \f21ajnd arriueth well.\f3 

2. \f21he fall of \f3Troy, \f2and wofall dole, \ 

y\v'-0.5'\h'-0.35m'\s6e\s0\h'0.35m'\v'0.5' seoona bodte doth tell.\f3 

3. \f21he tt^rrd of wandringes spea]ces, and father dead, and laid full lG^.\f3 

4. \f2In fourth Queene \f3Dido \f2bunies, & \(flames of raginge loue doth show,\f3 

5. \f211ie fift declareth plaies, axxl how the \(fleete vdth fier was oought.\f3 

6. \f2Qte sixt doth speake of 0iosts, and howe deepe \f3Plutoe8 \f2rGygne was souc^t. 

7. \f2The seuenth bocke, \f3Aeneas\f2 bringes vnto his fatall land.\f3 

8. \f2lhe ei^t prepareth «er, and power how foes for to vdthstand.\f3 

9. \f2The ninth of battels telles, and yet the captaine is aMay.\f3 

10. Aeneas \f2greeuous wrath \f3Mezentius, \f2in the tenth doth slay.\f3 

11. \f2Tlie eleuenth in vnequall \( fight \f3Camilla \f2castes to ground. \f 3 

12. \f 21316 twelfth with heauenly weapons giues to \f31\mms \f2raortall wound. \f 3 

13. \f2The thirteenth weds A\h'-0.35'ESieas wife, and brings him to etemall life 



Command line: troff —mm troff.aeneid | typesetter 
24 USER'S GUIDE 



Sampler 




THE ARGUMENTES OF 
the thirteene bookes of Aeneidos, 

expressed in verse. 

1. AENEAS, in the first, to Lyby land arriueth well. 

2. The fall o/Troy, and wofull dole, y second booke doth telL 

3. The thyrd of wandringes speakes, and father dead, and laid full low, 

4. In fourth Queene Dido burnes, & flames of raginge hue doth show. 

5. The fift declareth plaies, and how the fleete with fier was cought. 

6. The sixt doth speake of ghosts, and howe deepe Plutoes reygne was sought, 

7. The seuenth booke, Aeneas bringes vnto his fatall land. 

8. The eight prepareth war, and power how foes for to withstand, 

9. The ninth of battels telles, and yet the captaine is away. 

10. Aeneas greeuous wrath Mezentius, in the tenth doth slay. 

11. The eleuenth in vnequall fight Camilla castes to ground. 

12. The twelfth with heauenly weapons giues to Turnus mortal I wound, 

13. The thirteenth weds /Eneas wife, and brings him to eternall life. 
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File: pic.forms 



.p 

The fonns that \f IpicNfR provides are 
.HP 2 
.in +1i 
.PS 

circle "circle"; wove; boK "box"; wave; arrow "arrcw" above 

.FE 

.SP 2 

.PS 

ellipse "ellipse"; move; line "line" above; move; arc "arc" 
.FE 

.in -1i 
.P 

\£Xpic\£R's language is intuitive, so naking your cmh foxms is not hard. 
Bor instance, 

you can talk to \£Ipic\£R as you Msuld to scmeone drawing shapes with a pencil: 
.PS 

.in +0.3i 

ellipse; line right; arc; arc; arc; line down 1i; circle; arrow ri^t; box dashed 

line right; line dotted ri^; arc; arrow dashed; box "Tliere." 

.PB 

.in -0.3i 

Since you can store these instructions in special co n n an ds, you are able to 
ooDpile a personal library of shs^s, naming them whatever you like: 
.DS I 

ixqput_output 
molecularstruct 
solarsystem 
.DE 

Azvi these you can even tailor later to suit your particular needs in any document. 

For instance, the following exanple mi^ be used to demonstrate the concept of 

processing: 

.in +0.75i 

.sp 1 

.PS 

box "ii^jut"; arrow; ellipse "processing"; arrow; box "cutpit" 
.FB 

.in -0.75i 



Command line: pic picf orms | troff -mm | typesetter 
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The forms that pic provides are 





arrow 




line 



arc^ 



pic's language is intuitive* so making your own forms is not hard. For instance, you can talk to pic 
as you would to someone drawing shapes with a pencil: 




I 1 

Since you can store these instructions in special commands, you are able to compile a personal 
library of shapes, naming them whatever you like: 

inputjoutput 

molecular_struct 

solar_system 

And these you can even tailor later to suit your particular needs in any document. For instance, the 
following example might be used to demonstrate the concept of processing: 
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Introduction 



This tutorial shows you how to use mm, a collection of macros used to 
format letters, reports, memoranda, papers, manuals, and books. 

You should be familiar with the following terms and tools to benefit 
fully from the pages ahead: 

■ You should know what a file and directory are and how to 
create them. See the UNIX System V User Guide. 

■ You should know how to use a UNIX system text editor (for 
example, ed or vi) to create and change your own documents. 
See the UNIX System V User Guide. 

■ You should know how to run programs with options and 
arguments. See the UNIX System V User Guide, 

For a detailed description of the mm macros, refer to the "mm Technical 
Discussion." For more about the principles of text formatting, see the 
tutorial "The Formatter nro£f." 

You should use mm as you read through this tutorial, so that when you 
finish, you will be able to format documents with mm using its defaults. 
For some macros, you will be able to refine how they work with arguments. 
This tutorial provides several examples of lines before and after formatting; 
closely compare the input lines to the output lines to solidify your under- 
standing of how the mm macros work. 
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Formatting the Body of Your Document 

Suppose your file named report.in contains the following lines: 

f 

I started work with the 
Technical Writing Staff cn April 16. 
H/ writing assignments are: 
aocuEnentaticn for the BCS FOCIRAN Carpiler 
and 

dociznentation for the DistrUbuted 
l^ansaction Processing system (DfTPS) 2.0. 
.P 

My other activities this quarter were: 
I went to a conference, '^^riting About Oonixiters,'* 
at Acnoe State College, 
and I occpleted a group paced course 

offered ty AI61T Bell Laboratories Systeoas 'Kraining Center, 
"Overview of \s-1UNDC\sO system Intemals," 
\cn June 18 and 19. 



To format this file, type 

mm -Tip report.in > report.out 

This command line formats report Jn using the mm package and puts the 
result in a file named report.out. The option "-Tip" prepares the result for 
wide range of output devices. Ask your system administrator the device 
name of your local printer. 

The .P appearing in report.in is an mm macro that creates a new para- 
graph. The dot in column one cues the formatter to the presence of a line 
that should be executed rather than printed, that is, a control line. The 
upper-case letter P that follows the dot specifies the control that you want 
the formatter to exert. After you use the formatter, report.out should look 
something like this: 
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1 - 



I started work with the Technical Writing Staff on April 16, 
My writing assignments are: documentation for the BCS 
FORTRAN Compiler and documentation for the Distributed 
Transaction Processing System (DTPS) 2.0. 

My other activities this quarter were: I went to a 
conference, "Writing About Computers," at Acme State College 
and I completed a group paced course offered by AT&T Bell 
Laboratories Systems Training Center, "Overview of UNIX 
System Internals," on June 18 and 19. 

Constraints that are imposed by your terminal or printer may put more 
or less text on a given line than is shown here. The important thing to 
notice is that report.out does not look the same as reportan: there's a page 
number at the top, and lines are filled out from the left-hand margin, con- 
tinuing until the right-hand margin is reached. 

Notice that .P left-justifies paragraphs by default. You can give .P the 
argument 1 (type .P 1) to indent the first line of a paragraph five spaces. 
Try .P 1 to change the paragraph style in report.out. 



Formatting Lists (.BL, .DL, AL) 

Suppose that you want to list the work done for your writing assign- 
ments. Change your file named report.in to look like this: 
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.p 

I started work with the 

Technical Writing Staff en April 16. 

.P 

H/ writiiig assignments were 

.AL 

.LI 

doasnentaticn for the BCS FQRH^ CGopiler 

.DL 

.LI 

I collected materials relevant to inplementinj 
progranming languages on the IflCDC system. 
.LI 

I met and ta1ki?d with BCS FQRZFAN developers. 

.LB 

.LI 

documentation far the Distributed ^transaction 

Processing system iUTPS) 2.0. 

.DL 

.LI 

I reviewed USPS requirements, outstanding conplaints 
about DTPS, and users' suggestions for i m pro v ing 
DTPS dociznentation. 
.LI 

I attended two monthly DIPS planning meetings. 

.LE 

.LE 

.P 

other activities this quarter were: 
I went to a ocnferenoe, **Writing About Oooputers," 
at Acme State Oollege 
and I ooqpleted a group paced course 

offered by AiESiT Bell Laboratories Systems 'draining Center, 
"Overview of mix System Internals," 
.on June 18 and 19. 



Type 

mm —Tip report.in > report.out 

to put the result of formatting the modified text into a file: 
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- 1 



I started work with the Technical Writing Staff on April 16. 
My writing assignments were 

1 . documentation for the BCS FORTRAN Compiler 

- I collected materials relevant to implementing 
programming languages on the UNIX system. 

- I met and talked with BCS FORTRAN developers. 

2. documentation for the Distributed Transaction 
Processing System (DTPS) 2.0. 

- I reviewed DTPS requirements, outstanding 
complaints about DTPS, and users' suggestions for 
improving DTPS documentation. 

- I attended two monthly DTPS planning meetings. 

My other activities this quarter were: I went to a 
conference, "Writing About Computers," at Acme State College 
and I completed a group paced course offered by AT&T Bell 
Laboratories Systems Training Center, "Overview of UNIX 
System Internals," on June 18 and 19. 

All mm lists share the same general structure: they begin with a list- 
initialization macro such as .AL; they specify items with the list-item macro, 
.LI; and they end with .LE, which is the list-end macro. Here's an example 
of an automatically incremented list: 
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.LI 

The capital of Massachusetts is Boston, 
.LI 

The capital of New York is Albany. 
.LI 

The capital of North Caxolij^ is Raleic^. 



If you were to type these lines into a file called my,file/ and then typed 
mm my .file/ your processed file would look like this: 

1. The capital of Massachusetts is Boston. 

2. The capital of New York is Albany. 

3. The capital of North Carolina is Raleigh. 

The list-initialization macro that you choose usually determines the mark 
that appears before each list-item. For example, the .AL macro produces a 
numbered list by default. 

The file reportin uses two types of lists: a dash list (starting with .DL) 
nested inside an automatically incremented list (.AL). Before the .LE associ- 
ated with .AL occurs, .DL and associated .Lis appear twice. Whenever the 
formatter encounters a list-initialization macro, it puts everything (includ- 
ing other lists) on hold and attends to that list. When the .LE that ends the 
first dash list appears, the formatter picks up where it left off; notice that 
the list item between the dash lists becomes an automatically incremented 



In your report, you should acknowledge that UNIX is a trademark of 
AT&T. To do this, you can use a footnote. 




item. 



Formatting Footnotes (.FS, .FE) 
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.LI 

I collected materials relevant to iirplementijug 
progranniing languages on the wA* system. 
.PS ♦ 

Trademark of ATST 
.LI 

, I met and talked with BCS FGRHtAN developers. 

y 

Two macros delimit the text of a footnote: .FS signals the beginning, 
and .FE signals the end. These two macros are called a macro pair, since 
you cannot use one without the other. Think of a macro pair as you think 
of parentheses; it is incorrect to use the open parenthesis without the close, 
and vice versa. 

There are two ways to label a footnote in your document: 

1 . You can choose your own label by giving the .FS macro an 
argument. The label that you use in the document should 
be the label you use with .FS, to avoid confusion. In the 
example above, an asterisk is used as the footnote label, pro- 
ducing a footnote that looks like this: 



* Trademark of AIST 



THE MACRO PACKAGE mm 



7 



Formatting the Body of Your Document 



2. Rather than use a label, you can number footnotes automati- 
cally with the characters \*F. 

•LI 

I collected naterials relevant to iaxplementing 
prograniaing languages on the DNi3tV»F system 
.FS 

Tradenerk of AIST 
.FE 

This format produces a footnote that looks like this: 



1 . Trademark of 

if this is the first time you use \*F in the document. If it's 
the second time, your footnote is 



2. Trademark of ATSiT 
and so on. 

In the examjple above, an asterisk was used to label a footnote, but you 
can use any label or more than one (for example .FS ***). Your document 
may contain both labeled and automatically numbered footnotes. If you use 
\*F in the document, do not give the associated .FS macro a label, or you 
will get results that are hard to soft out. 



Labeled footnotes do not affect the incrementation of numbered footnotes. 



Creating Numbered Headings (.H) 

There are two categories of activities described in reportJn: writing 
assignments and everything else. To emphasize these categories in 
report.out/ use section headings. Use .H with an argument to create num- 
bered section headings: 
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,H 1 "Writing Assignnents" 
.P 

I started work with the Technical Writing Staff cn April 16. 
.BL 

etc. etc. 

.H 1 "Other Activities" 
.BL 

.etc etc 



The first argument to provides the numbered heading level and the 
second argument becomes the heading text. Enclose the heading text in 
double quotes if it contains spaces (for example "Second Level Heading"). 
For example 



.H 1 First 

.H 2 "SecGSii Level Heading" 

.H 2 "AiKJther Secooxl Level Heading" 

.H 3 "Third Level Heading" 

.H 3 "Another Ttaxd Level Heading (you can use up to seven levels)" 

.H 1 "Another First Level Heading" 

.H 2 "SecGSid Level Heading" 



produces headings like the following: 
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1. First 

1 . 1 Second Level Heading 

1.2 Another Second Level Heading 

1.2.1 Third Level Heading 

1.2.2 Another Third Level Heading (you can use up to seven levels) 

2. Another First Level Heading 
2.1 Second Level Heading 



Creating Unnumbered Headings (.HU) 

If you do not want to number your headings, you would use •HU: 
.HU "Other Activities" 

.HU acts the same as .H except that no heading mark is printed. When 
you use .H and .HU together, .HU increments the counter for level 2: 



.H 1 First 

.H 2 "Seccsid Level Headincr** 
.HU "First Unnundbered Heading" 
.HU "Second Unnumbered Heading" 
.H 2 "Second Level Heading" 



produces headings like these: 
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1 . First 

1 . 1 Second Level Heading 
First Unnumbered Heading 
Second Unnumbered Heading 
1.4 Second Level Heading 



Displays (.DS, .DE, .DF) 

mm gives you two ways to keep text blocks together: static displays and 
floating displays. Use the macro pair .DS and .DE to delimit static displays, 
which appear in the same relative position in your output as they do in 
your input. You can give .DS an argument to indent the whole display (by 
default approximately two spaces), as in the following example: 

C- ^ 

HKntAN — a programming language 
used for scientific applications, 

and in academia for a variety of applications, including: 

circuit analysis systens, 

statistical packages, 

and applications for engineers. 

J 

produces output like this: 

FORTRAN a programming language 
used for scientific applications, 

and in academia for a variety of applications, including: 

circuit analysis systems, 

statistical packages, 

and applications for engineers. 

Notice that displays leave text exactly as you typed it, unlike the paragraph 
macro, which fills in the line from the left-hand margin to the right (unless 
you give •DS a second argument; see the "The Macro Package mm: 
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Technical Discussion" in the Technical Discussion and Reference Manual), If 
you use .DS C instead of .DS I in the example above, each line of text in 
the display will be centered: 

FORTRAN a programming language 
used for scientific applications, 
and in academia for a variety of applications, including: 
circuit analysis systems, 
statistical packages 
and applications for engineers. 

If you want to center the entire block of text, rather than each line, use 
.DS CB: 

FORTRAN -- a programming language 
used for scientific applications, 

and in academia for a variety of applications, including: 

circuit analysis systems, 

statistical packages 

and applications for engineers. 

A Floating display, delimited by the .DF/.DE macro pair, "floats" 
through the input text to the top of the next page if there is not enough 
room for it on the current page; thus text that follows a floating display in 
the input file might precede it in the output file. The display text appears 
as you typed it, like the static display. 

You cannot nest displays and footnotes, in any combination, and you 
cannot put section headings within displays or footnotes. 



Creating Headers and Footers (.PH, .EH, .OH, .PF, 
.EF,.OF) 

Another handy set of mm macros formats page headers and footers. All 
header and footer macros take an argument of the form: 

"'left-part'center-part'right'part'*' 

This is a single argument, enclosed in double quotes and consisting of three 
parts, each part surrounded by delimiters (here, single quotes). In your out- 
put, these three parts are left-justified, centered, and right-justified. For 
example, 

.PH W. Williams' Technical Writing Staff' Page \\\\nP' " 
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produces a page header like the following: 

W. Williams Technical Writing Staff Page 1 

at the top of the first page of the document. The page number changes 
appropriately for pages that follow. 

You might wonder how \\\\nP in the input became 1 in the formatted 
file. P is a number register that contains the page number (do not confuse 
the number register P with the macro .P). Specifying \\\\nP in the argu- 
ment to the page header macro tells mm to print the contents of register P 
in the page header. This is not how you usually access number registers, 
but that's beside the point for now. You can read about this number regis- 
ter in the mm technical discussion in the Technical Discussion and Reference 
Manual, 

If need to use apostrophe ( ' ) within part of the header, use another 
character for the part delimiter: 

"♦Let's pat this left«TMs center*Let's put this right*" 

If you don't want to specify all three parts of a header, you don't have 
to. For example, leave out the left-part and center-part like this: 

If you don't specify a page header, the page number, enclosed by 
hyphens, appears in the center of your page. 

The other header macros work the same way that .PH does: .EH prints 
a line at the top of each even-numbered page immediately after the page 
header, and .OH does the same for odd-numbered pages. 

Footer macros work like header macros: use .PF for lines at the bottom 
of all pages, .EF for even-numbered pages, and .OF for odd-numbered 
pages. If you don't specify a page footer, you get a blank line. You can 
specify headers and footers anywhere in your file; they go into effect as 
soon as you use the appropriate macro. 
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You can show the title and the author's name at the beginning of 
report.in. This style, the formal memorandum, involves a special sequence 
of macros at the beginning of your input file: 

.TL 

Wbrk Progress Report ~ Seoooid Quarter 1984 
.AF "Business Gcinputer Systons, Inc." 
.AU "W. Wxlliaxns" m NY HDOT 1234 4-321 unixlw 
.HT 
.P 

I started work vd'Ui the 
Vrechnical Writing Staff on April 16. . . 



If you use any of the formal memorandum macros above, you must use 
them in the order shown to avoid a formatting error. Also, do not put any 
text or blank lines before .TL, or you will get a formatting error (parameter 
setting macros and requests are all right). 

If at the beginning of your file you use these macros and then specify 
page headers, the header that you specify appears on the second and follow- 
ing pages, not the first. Page footers that you specify at the beginning of 
the file appear on the first and following pages. 

The example above produces a mast for report.out: 
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AT&T Business Computer Systems, Inc. 



subject: Work Progress Report 
Second Quarter 1984 



date: November 1, 1985 

from: W. Williams 
NY HDQT 
4-321 X1234 
Unix I WW 



I started work with the Technical Writing Staff on April 16, . . 



Titles and Authors (.TL, .AU) 

Anything after the title macro .TL appears beside the word subject: in 
the formatted report. If your paper has more than one author, use a 
separate AU macro for each one, for example 

.AU "W. Williams" m NY HDQT 1234 4-321 unlxiww 
.AU "J. Bbley" JF XF 665415 6666 7-321 raachine_6l jf 

•AU is followed by the author's name (W. Williams), initials (WW), com- 
pany location (NY), department (HDQT), telephone number (1234), office 
room number (4-321), and machine address for electronic mail (unix!ww). If 
you need to, you may specify the author's title with .AT, which immedi- 
ately follows .AU for the given author. For example: 

.AT Supervisor "Technical Writing Staff" 

This title will appear in the signature block, which is discussed later. 
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The Name of Your Firm (AF) 

After your name (.AU and .AT), format the name of your firm with .AF. 
The default for .AF is ''AT&T Bell Laboratories/' which will appear when 
you do not use .AF. (You can change this default by asking your system 
administrator to edit the file /usr/lib/macros/strings.mm. See the "The 
Macro Package mm: Technical Discussion" in the Technical Discussion and 
Reference Manual) This macro puts its argument in bold letters in the upper 
right-hand corner of the page. 

.AU "W. Williams" m NY HDOT 1234 4-321 unixlw 
.AT Writer "Technical Writing Staff" 
.AF "Business Ccnpiter Systems, Inc." 

If you specify more than one author and more than one firm name, the 
last firm that you specify appears in the upper right-hand corner of the 
page. 

If you do not give .AF an argument, you suppress printing the name of 
your firm and the labels subject: date: and from:, which are associated with 
formal memoranda. However, the information you provide .TL and the 
other formal memorandum macros will appear in their usual positions at 
the top of the page. 



Choosing the Memorandum Style (.MT) 

.MT specifies the formal memorandum style (versus the business letter 
style, described below). If you use the formal memorandum style, you may 
use an argument to specify one of three types: the memorandum, the 
released-paper, or the external letter. The mast above was produced with 
.MT 0, which corresponds to the memorandum type. If you do not provide 
an argument to .MT, or if you type .MT 1, you will produce a slightly 
altered memorandum type mast; MEMORANDUM FOR FILE will appear a 
few lines after the last line of information about the author (unixiww). 
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AT&T Business Computer Systems, Inc. 



subject: Work Progress Report 
Second Quarter 1984 



date: November 1, 1985 



from : 



W. Williams 
NY HDQT 
4-321 X1234 
unix I WW 



HEHORANDUH FOR FILE 



I started work with the Technical Writing Sta££ on April 16. 

Thus by giving .MT different arguments, and changing nothing else, you 
make the same beginning macros (.TL, AU, etc.) generate sUghtly 
different masts for the memorandum type. The mm technical discussion 
in the Technical Discussion and Reference Manual lists all the arguments 
available for .MT. 

You get an entirely different mast, associated with the released paper 
type, by specifying .MT 4 instead of .MT 0. The released paper mast 
looks something like this: 



Work Progress Report Second Quarter 1984 
W. Williams 
AT&T Business Computer Systems, Inc. 

I started work with the Technical Writing Staff on April 16. . , 
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You can get the mast associated with the external letter type by 
specifying .MT 5. The external letter mast looks something like this: 



Work Progress Report 
Second Quarter 1984 



November 1, 1985 
I started work with the Technical Writing Staff on April 16. . . 



The Sampler in this book shows memoranda laid out with formal 
memorandum macros, before and after formatting. 
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In contrast to the formal memorandum style produced with .MT, you 
can obtain an entirely different style using a set of macros designed to pro- 
duce common business letters. 

Suppose that you wanted to include information from report.in in a 
full-blocked letter (the addresses, salutation, and so on, are left-justified). 
Instead of using the sequence .TL, .AU, .MT, use the following lines: 



,m "W. WHliams" 

Business Ocnpiter Systems, inc. 

190 River Boulevard 

Durham, NC 27707 

.WB 

,ID SA "Dear Mr. Smith:" 
.ID CN 

.lA "Bob acDith" "Personnel Chief" 

Sximnit Research Ccnpamy 

38 River Road 

Sutmdt, NJ 07901 

.IE 

.LT FB 
.P 

I enjoyed meeting with yon last T\iesday. 

Here, as I pronised then, is a description 

of my activities with Business Conputer Systents, Jnc, 

.P 

I started work with the Technical Writing Staff on 
April 16. 
etc. etc, etc. 
.PC "Sincerely" 
.86 
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Letter Type (.LT) 

mm offers four types of business letters; choose one by giving .LT (the 
letter type macro) an argument: 

.LT FB produces the full-blocked type (as above) 

.LT SB produces the semi-blocked type 

.LT BL produces the blocked type 

.LT SP produces the simplified type 

The mm technical discussion in the Technical Discussion and Reference Manual 
explains these letter types. 



Addresses (.WA, .WE, .lA, .IE) 

The macro pair .WA and .WE formats the writer's address, and the pair 
.lA and .IE formats the "inside" or recipient's address. You must give an 
argument (the writer's name) to the macro .WA, but with .lA, this argument 
is optional. You also have the option of specifying a title (for example Per- 
sonnel Chief) as a second argument to both macros. 



Letter Options (.LO) 

Use the letter-options macro .LO to format several common components 
of a business letter; the example above prints a salutation (.LO SA "Dear 
Mr. Smith:") and the line "CONFIDENTIAL" (.LO CN). You can produce 
other components of a letter by giving other arguments to .LO. For exam- 
ple, .LO SJ prints a subject line. 

SUBJECT: 

If you specify the line .LO SJ "Description of Activities" for any business 
letter type besides the simplified type, the line prints the following on the 
second line below the salutation: 

SUBJECT: Descxiption of Activities 

If you use the simplified type, this control line produces: 
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DESCRIFnOK OF ACTIVITIES 

You must use .WA and .WE^ J A and .IE, and .LT in that order, or you 
get a formatter error. Also, if you use any of these letter macros in the same 
file you that use formal memorandum macros (for example, .TL or .MT), 
you will get confusing results. The Sampler in this book shows a business 
letter using these macros, before and after formatting. 
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Most macros to format the end of a document work with both formal 
memoranda and with business letters. 



Formal Closing (.FC) and Signature Block (.SG) 

To close reportJn with "Yours very truly/ use .FC after the body of the 
document. If this closing seems too formal, specify an argument to .FC for 
a different closing: 

.PC "Sincerely yours," 
.SG 

.SG (for signature line) prints each author's name after the formal clos- 
ing; otherwise each name appears a few spaces down from the last line of 
the body of the memo. The formatter collects the author's name from .AU 
(or .WA) for .SG to use. For example, the following lines were used to 
specify authors above: 

r 

"W. millazns" m m HDGT 1234 4-321 unixlw 
.AT Writer "Technical Writing Staff" 
.AU "J. Foley" JF XF 665415 6666 7-321 inachine_6 1 jf 
.AT St^jervisar "Technical Writing Staff" 

V 

Now, if you use .FC "Sincerely yours/ and .SG at the end of your report (as 
above), the following signature block will appear centered in the output: 




22 USER'S GUIDE 



Formatting the End of Your Document 



Sincerely yours, 



W. Williams 
Writer 

Technical Writing Staff 



J. Foley 
Supervisor 

Technical Writing Staff 

Three blank lines are left above each name for an author's signature. You 
can use either .FC or .SG by itself. 



Approval Line (.AV) 

If your memorandum requires a line for a signature signifying formal 
approval, use .AV: 

.AV "Todd Doe" 

produces 

APPROVED: 



Todd Doe Date 

You can use .AV anywhere on the page, but it is most commonly used 
between the signature block and the "Copy to" list. 
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Formatting the End of Your Document 



Copy to Lists and Other Notations (.NS, .NE) 



Use the macro pair .NS and .NE to print notations for lists of attach- 
ments or "Copy to" lists after the signature block. For example: 



.NS 

J. Foley 
J. Jones 
W. Winiants 
.NE 



Copy to 
J. Foley 
J. Jones 
W. Williams 

List the recipients of your document between .NS and .NE. This macro 
• provides proper spacing and breaks notations properly across pages. 

Use arguments to .NS to get more specific "Copy to" lists. For example: 







prints 





Bill Taylor 
.NS 2 
J. Qcaven 
A. Greenland 





produces 



24 USER'S GUIDE 



Formatting the End of Your Document 



Copy (with att. ) to 
Bill Taylor 

Copy (without att.) to 
J. Craven 
A. Greenland 

Some examples of memoranda and business letters formatted with mm 
appear in the Sampler at the beginning of this User's Guide. 



Moving On 

You now have a good grasp of the formatting power of mm. This 
tutorial was not intended to teach you everything about mm; it was meant 
to sketch out enough for you to start using mm right away. Read The 
Macro Package mm: Technical Discussion" in the Technical Discussion and 
Reference Manual to learn the technical intricacies of mm. 
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Introduction 



nroff is a text formatter for typewriter-like printers and terminals. A 
text formatter manipulates text by interpreting special commands that you 
place between the lines for which you want formatted output, nroff allows 
you to format a variety of documents, including letters, reports, and books. 
You will learn the basics of nroff by using this tutorial, following the exam- 
ples that it provides. 

The prerequisites to benefit from this tutorial are as follows: 

■ You should know what a file and directory are and how to 
create them. See the UNIX System V User Guide, 

■ You should know how to use a UNIX system text editor (for 
example, ed or vi). See the UNIX System V User Guide, 

■ Some experience with mm is helpful, but not necessary, in 
making the most of this tutorial. See the tutorial "The Macro 
Package mm: A Tutorial" in this book. 



The Formatter troff: a Tutoriar in this book describes a related but more 
NOTC powerful set of requests that you can use to prepare text for photo- 

_J typesetters. For details about using nroff, refer to the "nroff Technical Dis- 

I cussion" in the DOCUMENTER'S WORKBENCH Software Technical Discussion and 

Reference Manual. 

After reading this tutorial, you will be able to control many attributes of 
your formatted document, including the margins, indentation, hyphenation, 
characters per line, and lines per page. You also will know how to use 
number registers, define strings, and create simple personal macros. This 
tutorial provides several examples of lines before and after formatting; 
closely compare the input lines to the output lines to solidify your under- 
standing of nroff 's workings. 
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Requesting Space (.sp) and Indentation (.ti, 
an) 

Suppose you have a file named file.in that contains these lines: 



I'm glad I'm not a pair of ragged claws, scattlang across the floor 

of seafood restavirants. 

*rtds is the last line of this paragraph. 

.sp 2 

.ti +5m 

This is the first line of a new paragraph. 
OSiis is the second line. 
OMs is the third line. 
.This is the fourth line, and so en. 



Besides text, file.in contains two requests: .sp and .ti. .sp 2 requests two 
lines of space between text lines, and .ti +5m requests that the next text line 
be indented five ems (one em is about the width of the letter m). The dot 
(.) in column one alerts nroff to the presence of a line that should be exe- 
cuted rather than printed, that is, a control line. The two lower-case letters 
that follow this dot specify the control that you want nroff to exert. Argu- 
ments to requests, like 2 to .sp and +5m to .ti, refine how they work. 

Requests are the simplest control lines that the DOCUMENTER'S WORK- 
BENCH Software offers. Each request performs a single formatting task. 
Macros, in contrast, combine requests in special ways, and thus do several 
formatting chores. Later in this tutorial, you will learn how to create and 
use macros in addition to those that are already available with mm. 

To format file.in and to put the results into a new file, type this com- 
mand line: 

nroff file.in > file.out 

You can look at file.out on your terminal after the shell prompt returns, or 
you can send file.out to a printer with 

cat file.out I Ip 

or send it directly with 
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Requesting Space and Indentation 



nroff file.in | Ip 

A printed version looks like this: 

I'm glad I'm xxrt: a pair of ragged claws, scuttling across 
the floor of seafood restaurants. Ihis is the last line of 
this paragraph. 



Uiis is the first line of a new paragraph. This 
is the second line. This is the third line. This is the 
fourth line, and so on. 

Your printer or terminal may insert more or less text on a given line 
than this example shows. The important thing to notice is that file.out does 
not look the same as file.in. Using nroff, you have the power to make 
file.out look precisely the way you want. You can command nroff to insert 
more (or fewer) blank lines or to indent more (or fewer) spaces by changing 
the arguments to these two requests. Try putting three spaces between the 
paragraphs, and indenting the new paragraph seven ems. 

The .ti request (temporary indent) indents only the line that follows it; 
the second and following lines of text return to the left margin. This 
request is helpful when formatting paragraphs. To move all output lines to 
the right seven spaces, use .in instead of .ti; then the indent is more than 
temporary. The contents of file.in looks like this: 

f 

Here, tesct is flush left, 
.in +7m 

Notice that with the indent request, all 
text lines are indented seven eoos from the current left 
nargin. 

Notice how this differs from the tenqporary inclent reqpiest. 
. .in 

\ncw, tejct is flush left again. 



A printed copy of file.out appears as follows: 
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Requesting Space and Indentation 



Here, text is flpsh left. 

Notice that with the indent request, all text 
lines are indented seven ems from the current 
left margin. Notice how this differs from the 
temporary indent request. 

Now, text is flush left again. 

Here, you indent lines in output seven ems until you set them flush left by 
typing .in 0. Typing .in without an argument sets indentation where it was 
before you last used .in. Initially, nroff sets indentation to (flush left), so 
in the example above, .in would work the same a^ .in 0. 

Instead of resetting the indentation to 0, you may want to set it to 
another value. Consider the contents of file.in: 



Here, text is flush left, 
.in +7m 

With the intient request, all 

text lines are iiidented seven ems from the current left 
margin, 
in —3m 

. Nofw, text is four ems from the left nargin (7-3 = 4) . 



A printed copy of file.out follows: 

Here, text is flush left. 

With the indent request, all text lines are 
indented seven ents from the current left mar- 
gin. 

Now, text is four ans fron the left margin 
(7-3=4). 
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Line Filling (.nf, .fi) and Line Breaks (.br) 



Notice that the number of lines you type in is not the number nroff 
puts out. Besides interpreting control lines and making them disappear 
from the output, nroff rearranges your text, filling the page with tightly 
formatted output. 

nroff fills lines automatically. When line filling is on, words accumu- 
late in a line buffer until it is full, and then the buffer is flushed, file.in is 
as follows: 



lliis means that vrozds fill a line, 
regardless 

of their position on the page as they are iiqjut, 
.nf 

The "no-fill" request 

turns off line filling, 

maJdng output the same as input. 

.fi 

Line filling stays off 

unless you turn it back an with the fill request. 



A printed copy of file.out appears as follows: 

T3iis means that words fill a line, regardless of their posi- 
tion C3n the page as they are input. 
Ttie "no-fill" request, 
turns off line filling, 
making output the same as di^put. 

Line filling st:ays off unless you t:um it bacdc on with the 
fill request. 



nroff also flushes the line buffer when it finds a line break. As you may 
have noticed, .sp forces a line break and produces lines of space. The .br 
also forces a new line. Consider this version of file.in: 
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Line Filling and Line Brealcs 



An esqplicit break request 
.hr 

starts a new lijie 

but does not insert a line of space 
between the lines of text it separates. 



file.out prints as follows: 

An explicit break request 

starts a new line but does not insert a line o£ space 
between the lines of text it s^^arates. 
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Hyphenation (.hy, .nh, .he, .hw) 

Notice that when nroff fills lines, it only puts out whole, never 
hyphenated, words. By default nroff does not hyphenate. To turn on 
hyphenation anywhere in your text use .hy. When you switch on hyphe- 
nation, you may put a hyphenation indicator in a text word to specify 
places where the word should be hyphenated if need be. Set this hyphena- 
tion indicator with .he. file.in looks like this: 




.he @ 

Hew would you use the extremely long 
word pneu@ioric@ultra@nicxosoi:pic@isi^^ 
in a sentence? 




The formatted, file.out follows: 

How TOold you lase the extreroely long ward pnesuraorKDultra- 
inicroscopicsilicx3Molcanooaniosis in a sentence? 

From this point on, nroff interprets the character "@" as an acceptable place 
to put a hyphen, if needed. After inserting the hyphen, nroff flushes the 
line buffer and starts a new line, nroff hyphenates words not containing 
the hyphenation indicator wherever it wants. Do not use .he without 
turning on hyphenation with .hy. 

If you want to specify particular words to be hyphenated in a particular 
way, use the request .hw: 
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Hyphenation 





.Ym anti-cliinax 

Olie resolution of the silly plot is an anticlimax* 
Ihis director should be fired. 





Now, every time nroff finds "anticlimax" at the end of a buffer, it tries to 
hyphenate it the way that you specified, not "an— ticlimax" or "anticli—max." 
If the word cannot fit on the line the way you have specified it, nroff does 
not try to hyphenate it. 
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Centering (.ce) 



•ce centers as many text lines as its argument specifies. With no argu- 
ment, .ce centers one line. Here's file.in: 

Ihe centering cxnnBnd is effectively a "no-fill" ccnnond, 
except that cutout lines 
are centered instead of flush left. 
If you use the no-fill oamBnd with 
.ce 4 

MiB centering oomand, centering takes charge. 
Ihe next three lines and the line preceding are centered, 
.fi 

But now you hsrve turned cn line filling. 
What happens to the centering? 
Vllie answer is that centering has priority over filling. 



The printed version, file.out, looks like this: 

The centering ccnuand is effectively a "no-fill" ootipcOKi, 

eacoept that the output lines 

are centered ijistead of flush left. 

If you use tlie no-fill odcitand with 

the centering ocnmandy centeriiig takes charge. 
The next 3 lines and the line preceding are centered. 
Bat now you have turned cn line filling. 
What happens to the centering? 
The answer is that centering has priority over filling. 



J 
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Justification, Unpaddable Space (.ad, .na) 



nroff ordinarily gives you even (jxistified) left and right margins, (mm 
gives you a ragged right margin by default.) To change margin justification, 
use .ad, as this version of file.in demonstrates: 

Here, you've given the adjustment request the argument "1". 
Hhis tells nroff to justify only the left nargin. 
Many people prefer a ragged right oargin. 
.ad b 

With the "b" argument, .ad justifies both left ana right nargins. 
Khen there is an even rig^ and left nexgin, 
nroff pads the line b/ eiqaanding spaces. 
fOiis viay Tprodjjse text alignnent uipleasing to the eye. 
.na 

Ihe "no adjustment" request turns ric^t jxistificatdon off (that is, the 
\ left margin is justified, but the ric^t margin is not) . 



The printed versions appear as follows: 

Here, you've given the adjustment request the argument "1". 
aiiis tells nroff to justify only the left itBrgin. Many peo- 
ple prefer a ragged right nargin. With the "b" argument, 
.ad justifies both left and ri^t margins. When there 
is an even right and left nargin, nroff pads the line by 
expanding spaces. Ihis may produce t:ext alignment 
uipleasing to the eye. 15ie "no adjustment" request turns 
right justification off (that is, the left msujgin is justi- 
fied, but the right nargin is not) • 

One way to adjust the right margin and maintain a line pleasing to the 
eye is to specify a space that nroff cannot expand during justification. To do 
this, type a backslash followed by a space *^ " , an unpaddable space, at 
places nroff had padded. The backslash is an escape character; you will find 
out more about this below. 
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Justification, Unpaddable Space 



An alternative to using unpaddable spaces is to request that some 
seldom-used character, such as a tilde ('), be translated into a space on out- 
put. To do this, use the "translate" request 

.tr • 

(that is, dot tr space tilde space). If you find that you need a tilde later in 
the output, turn it back into a tilde it by inserting this line: 

•tr 

(dot tr space tilde tilde). Later, you may restore the tilde as an unpaddable 
space by repeating .tr *, but only after a line break or after nroff outputs the 
line containing the tilde. 

What do you suppose happens to the text below when you format it? 

.adb 
.ce 2 

What request wins out? 

Will there be adjustment, or centering? 

Remember what happened when .fi competed with .ce? Here as there, 
lines after .ce are centered, despite the request for adjustment. After that, 
left and right margins will be adjusted until you change adjustment or until 
you use .na. 
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Setting Tabs (.ta) 



nroff automatically sets tab stops every eight ens from the current 
indent, but you can change these stops with .ta. Here's file.in: 



.ta 0.5i 1.5i 2.5i 3.0i 

'Stie next liite OGntains tabs; the tab request 
places the tab stops at particular places: 

Here is a line with tabs, 

.ta 1.5i 2.5i 3.0i 3.5i 

The next line also contains tabs, but the tab request places the 
steps differently fran above: 

Here is a line vdth tabs. 



The file comes off the printer looking like this: 

13ie next line ccoitains tabs; the tab request places the tab 
stops at particular places: 

H^e is a line with tabs. 

Ihe next line also contains tabs, but the tab request places 
the steps differentily from above: 

Here is a line with 

tabs. 

These tab stops are left-justified, but you can set up right-justified tab stops 
or centered tab stops, too. For details about how to do this, refer to the 
chapter "nroff Technical Discussion" in the Technical Discussion and Reference 
Manual, 

If you want to position numbers, or if you need more complicated 
columnar layout, use tbl, which is described in the chapter The Preproces- 
sor tbl" in this guide. 
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Selecting a Font (.ft) 



nrotf is frequently used with mechanical printers like daisy-wheel 
printers, which produce documents by striking pre-cast characters as they 
turn on a wheel. Using such a printer, nro£f can provide three distinctions 
among fonts. It can provide a regular font by default (.ft R or \£R); it can 
represent an italic font by having the printer underline (.ft I or \fl); finally, 
it can provide a bold version of the regular font by having the printer back 
up and overstrike characters (.ft B or \fB). nroff thus understands three 
fonts — regular, italics, and bold— even when it is used with a basic mechan- 
ical printer. When nroff is used with a more advanced printer, such as a 
laser printer or sophisticated dot matrix printer, it can provide a more pleas- 
ing version of regular (or roman), italics, and bold: 

abcdefghijklmnopqrstuvwxyz 0123456789 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 
abcdefghijklmnopqrstuvwxyz 0123456789 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 
abcdefghijklmnopqrstuvwxyz 0123456789 
ABCDEFGHIJKLMNOPQRSTUVWXYZ 

To switch fonts, use the .ft request: .ft B for bold, .ft I for italic, and .ft 
R for roman. To return to the previous font, whatever it was, use either .ft 
P or .ft with no argument. Once you change fonts with .ft though, nroff 
uses the font that you specify until you change fonts again. 

Another way to italicize text is to use the .ul request. Depending on 
your printer, .ul underlines the next input line or italicizes it. Follow .ul 
with an argument that requests the number of input lines to be italicized, 
for example .ul 3; otherwise, only the line that follows the request is itali- 
cized (much the same way that .ti indents only the line that follows it). 

Fonts also can be changed within a line or word with the escape 
sequence \f . Consider the contents of this file: 

\fBbold\fIface\fR text 
A printed version looks like this: 
bold/ace text 

An escape sequence is a special in-line command that begins with the 
escape character \ (backslash). This character tells nroff that what comes 
next is special; thus f is interpreted as "font" instead of as the letter "f." 
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Selecting a Font 

To avoid losing the last font requested after each in-line change, restore 
it with the escape sequence \£P, since nroff remembers only the last font 
called. For example, in the next line, the last \f P restores the font to what- 
ever the font was before \f B: 

\fBbold\fP\flface\fP\fR text\fP 

In this next example, the \f P restores the font to italic: 

\fBbold\nface\f 1 text\fP 
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Margins (.po), Line Length (.11) 



If you are not content with the page dimensions that nrotf gives you, 
you can change them, file.in looks like this: 



You can change the left loargin with .po, vMch stands for "page offset." 
Here, nroff adds one inch to the esdsting left 
margin to deterndne the new margin, 
.po +1i 

Here's another line of text, 
.po 

Cnce ycu change the nargdn, any indentation is relative to the new value. 
*to restore the previous left nergin, type .po without an argument 



A formatted version looks like this: 



You can change the left nergln vath .po, vMch starK^s for ''page 
offset." Here, nroff adds one inch to the existing left margin to 
determine the new nergin. 

Here's another line of text. Once you change the 
margin, any indentation is relative to the new 
value. To restore the previous margin, type .po 
withcjut an argument. 



Even though .po may appear to do the same thing that .in does, it 
doesn't. The formatting request .in indents from the current left margin, 
while .po changes the current left margin. 

Look carefully at this last example. Notice that part of file.in before the 
second .po is not offset three spaces on output. Remember, nroff works 
with line buffers, not lines as you have typed them. After the second .po, 
the next buffer, not necessarily the next text line, that nroff flushes is the 
first to obey this request. 

Also notice that nroff translates the escape sequence \& into a character 
that does not print. \& is useful when you want to treat a control line as 
text rather than as something to be executed. Putting this non-printable 
sequence in columns one and two, before the dot in a control line, nullifies 
the line's control (as the last example shows). Use \& consistently before 
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Margins, Line Length 



any control sequence that you want to nullify, regardless of its current posi- 
tion on a line since when you edit text, the position of words or characters 
may change in unexpected ways. 

The .11 request changes "line length," Here's £ile.in: 



,11 +3 

Ycu can change the le£t nazgin witii .po, %diich stands for "page offset. 
Here, nroff adds one inch fzoa the existing left 
nazgin to detexndne the new margin, 
.po +1i 

Here's another line of text, 
.po 

If yen change both the line lengtii \2and\F the left cazgin, you get 
.different results than if you sinply change the cargin. 



The formatted version looks like this: 



Qiange the left margin vath .po, vdiich stands for "page offset." Here, 
nroff adds ctne inch f rem the existing left nargin to determine the nevr 
margin. 

Kerens another line of text. If yoa change both the line 
length and the left nargin, you get different results than 
if you sinply change the nargin. 

As you can see, the line length has in fact extended the right margin. 
Thus, to decrease the right margin, you increase the line length with .11. 

Notice that some of the requests covered so far take alphabetic argu- 
ments and some take numeric arguments, preceded or not by a plus or a 
minus sign. To know what's appropriate for any given request, check 
the "nroflf Technical Discussion" in the Technical Discussion and Reference 
Manual, 

For now, consider the use of + and — before a number. These sym- 
bols change the previous setting by the amount you specify, rather than 
by just overriding it. The distinction is important: .11 +3 makes lines 
three characters longer; .11 3 makes them three characters long. 
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Page Length (.pi), Page Breaks (.bp), and 
Page Numbers (.pii) 



Now you have control of the width of your printed page, but what 
about the length? By default, nroff gives you a page 11 inches long. If you 
want to change the page length, that is, change the amount of space that 
nroff leaves between the text and the physical top and bottom of the page, 
use .pi. 



Here, .pi has an argument that consists of a number and a letter. This letter 
corresponds to a scale. If you do not specify i (which stands for inches) and 
simply type .pi +1, nroff assumes that you want to increase the present 
page length by one line space. 

You also may specify units for .11, .po, .in, and .ti. The default unit for 
.in and .ti, as for most horizontally oriented commands, is eins. (Remember, 
one em is roughly the size of the character "m".) 

If you want to start a new page, use .bp, which stands for begin page. 
The input file looks like this: 



Pond so, in ocnclusicai, ani so on. 
This is the last sentence of a paper, 
.hp 



.pn stands for "page number." The next page, when it occurs, will have 
the page number that you specify as the argument to this request. Pages 
that follow will also increment from this new page number. 



.pi +li 



.ce 




BEFEBEtCES 
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Keeping Lines Togettier (.ne) 



At times you will want to prevent certain lines from being split across 
pages. Use .ne to tell nroff the number of lines of text that you want kept 
together. Here's an input file using •ne: 



.nf 
.ne 4 

M/ address is: 
John Stoith 
1956 Malcolm Road 
HccoetoMn, USA 
.fi 



would print the four lines of text on the next page if there was not enough 
room for all of them on the current page. 
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Defining a String (.ds) 



A string is a named collection of characters not including a newline 
character. Once you have defined a string with .ds, you can use the string 
name as shorthand for its contents. The following is fileJn: 



.ds s6 string 

Defining your cmn \*(s6 is oonvenient vhen 

yoa use a particular vrord 

or sequence of characters nan/ times. 

Tb define a \*(sG, type .ds, tlien the string name, and then its 
definition. 

Note that \»(sG is replaced ty its definition, the word "string," 
throughout this paragraph vihen you format it. 
HcK(^ you interpolate a \«(9G depends en 
vdiether the \*(g6 name is one car two (diaracters long. 
If the \»(sG is cne letter long, type "\*" 
and then the \(*s6 name. 
If the \»(sG is two letters long, type "\*(" 
.and then the \*(s6 name. 



The processed file looks like this: 

Defining your own string is oativenient when you use a par- 
ticular vx>rd or secpence of dharacrters nany tujnes* To 
define a string, type .ds, then the string name, and then 
its definitzion. Note that string is replaced by its defini- 
ticai, the ward "string," throuc^iout this paragraph \fghen you 
foonat it. How you interpolate a string depends en whether 
the stxing name is one or characters long. If the 
string is one letter long, type "\*" aiKl then the string 
name. If the string is two letters long, type "\*(" and 
then the string name. 



Remember that a backslash tells nroff that what follows is special in 
some way. Escape sequences allow in-line control of formatting, such as the 
interpolation of strings. The backslash begins all escape sequences like \*. 
The "nroff Technical Discussion" in the Technical Discussion and Reference 
Manual lists and describes all available escape sequences. Typing \e tells 
nroff to interpret \ as the character, backslash, not as the beginning of 
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Defining a String 

an escape sequence. 

If you must begin a string with blanks, define it as follows: 
.ds XX " text 

The double quote signals the beginning of a definition. There is no need 
for a trailing quote; the end of the line ends the string. 

A string may be several lines long; if nroff encounters a \ at the end of 
any line of the string definition, the backslash is thrown away and the next 
line added to the current one. So you can create a long string simply by 
using the backslash like this: 

.ds XX this \ 
is a very \ 
longr strinQf 
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Using Number Registers (.nr) 



Number registers, like strings, can be useful in setting up a document 
that you can change easily later, nroff can do arithmetic with these number 
registers, which hold numeric values that control aspects of output style. 

Like strings, number registers have one or two character names. They 
are set by the .nr command and can be used anywhere in your input by typ- 
ing \n and then the name (for a one-character register name) or \n( and the 
name (for a two-character register name). 

There are many predefined number registers maintained by nroff, 
among them % for the current page number; dy, mo, and yr for the current 
day, month, or year; and •f for the current font (which is a number from 1 
to 3: 1 for roman, 2 for italic, and 3 for bold). Any of the predefined regis- 
ters listed and described in the "nroff /troff Technical Discussion** in the 
Technical Discussion and Reference Manual may be used in computations, but 
some, like .f , cannot be changed by .nr. The following example puts the 
page number and the current date in a page title («tl). 

.tl 'John Soaith' NaK' \n(no-Nn(cbr-\n(yr' 

Titles are easy; the whole argument to .tl appears as the next line of output. 
The first part of the argument (John Smith) appears in the left-hand corner 
of the page, the second part appears centered, and the last part appears 
right justified, like this: 

Jdm Sftdth 21 12-18-85 
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Using Number Registers 



Here's another example using nroff number registers. file.in looks like 
this: 



.in (\n(.l+\n(.i)/2 

'Shis starts lines in the center of the page, regardless of line length. 

nie request subtracts the current inclent (contained in the nurhber 

register \f3.i\f1) from the current line 

length (contained in the nunber register \f3.l\f1}, 

divides the result hy two, and indents by that amount. 

.in 

If you do SGBoething like this, you mi^xt mnt to put 
indentation bade to the left nargin at sone point. 



The formatted version looks like this: 

Ihis stazrts lines in the 
center of the page, regardless 
of line length. Uie request 
subtracts the current indent 
(contained in the number 
register .1) from the current 
line length (contained in the 
number register J), divides 
the result hy twD, and indents 
by that aitount. 
If you do sonsething like this, you might wont to put 
indentation back to the left norgin at some point. 
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Creating a Simple Macro (.de) 

A macro is a shorthand notation similar to a string; it names a collection 
of requests. When would you want to use a macro rather than a request? 

Suppose you want to format every paragraph in a document differently, 
some with two spaces between them, some indented, some not. Here, it 
would be reasonable to use requests, since they provide that degree of flexi- 
bility. On the other hand, if you wanted to format paragraphs uniformly, 
you should use a macro, mm provides a collection of pre-defined macros 
that you can use to format several types of documents. However, if you do 
not want to use mm for some reason, you may write your own macros. 

For example, in the Sampler file nroff .letter, two requests format every 
paragraph: one request puts a space between the paragraphs (.sp) and the 
other indents the first line five spaces (.ti +5). To create your own macro to 
do the job of these two requests, use the .de (for define) request. 

You can call your paragraph formatting macro .pD (for paragraph 
definition). Here is how you use .de to create .pD: 




The control line closes the macro definition. You can define macros any- 
where in your file that you wish, but it is better to keep all macro 
definitions at the beginning of your file, for easy maintenance. 

After you define your macro, you can call it by name 

.pD 

and it does the tasks specified by the two requests that it incorporates. 
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Creating a Simple Macro 



Here is a macro that starts a new page and centers the macro's argument 
at the top of that particular page: 



.de nM \"i)ew page nast 

.hp \"begin a new page 

.sp 2 \"twD lines of space 

.ce X^oeixter the next line 

.sp 3 Vthree lines of space 



Inside this macro definition, the string \\$1 refers to the first argument that 
you give .nM (for example, .nM REFERENCES), placing it after .ce. Thus, 
the argument that you give .nM gets centered. This centered mast is placed 
two blank lines down from the top of the page, and then three blank lines 
are put out. 

You may wonder what happens to the words new page mast, and so on, 
inside this macro, nroff throws anything after \" away, and then goes to the 
next line, nroff recognizes V as the beginning of a comment. (Use spaces 
instead of tabs to set off comments.) 

Here's a more elaborate paragraph macro. 



.de tG \"new paragraph 

.ft R \"ranan font 

.sp Vcne line c£ space 

.ne 31 \'*need three inches 

.in \"flush left 

.ti -1-6 X^indent next line six 



In this macro, nroff loads roman font, puts out a space, sees if there are 
three inches of space left on the page (if not, it skips to the next page), sets 
the indent to the left margin, and then indents the first line six spaces. 



24 USER'S GUIDE 



Creating a Simple Macro 



Why go to the trouble of setting the indent flush left and then indent- 
ing six spaces? Why not simply indent six spaces? You never know where 
your text has been. Earlier in your file, you may have made a request such 
as an +10. The line .in resets indentation and puts the following text at 
the current left margin. Similarly, loading roman font is a way of ensuring 
that if you have forgotten to restore roman earlier, you have set things right 
with this new paragraph. 

Notice that these macro names consist of a lower-case letter followed by 
an upper-case letter. It is good practice to stick to this pattern so that you 
do not accidentally redefine an mm macro. 
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Moving On 



If you want to learn more about hroff, scan the material in the 
"nroff/troff Technical Discussion" in the Technical Discussion and Reference 
Manual and find a request that you think would be useful. Read the 
material, and then experiment with the request. For example, take what 
you have learned from this tutorial and explore more complicated uses of 
number registers and strings. 

The troff tutorial in this guide explains more complicated requests and 
macros you can define yourself. As mentioned before, troff is a more 
powerful set of requests that provide precise phototypesetting capabilities. 
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Introduction 



This tutorial teaches the basic principles of tbl, a program that produces 
simple and complex tables. With tbl, you can align columns of numerical 
data, equations, or text. You can draw horizontal or vertical lines in the 
table and enclose any table or table element in a box. 

The prerequisites to benefit from this tutorial are as follows: 

■ You should know what a file and directory are and how to 
create them. See the UNIX System V User Guide. 

■ You should know how to use a UNIX system text editor (such 
as ed, vi, or ex). See the UNIX System V User Guide, 

■ You should know how to execute commands and how to use 
options and pipes. See the UNIX System V User Guide. 

■ Your understanding of tbl would be assisted by a knowledge 
of the mm macro package and of nroff . See the tutorials in 
this guide, "The Macro Package mm" 

and "The Formatter nroff." 

For a detailed description of tbl, see the "tbl Technical Discussion" in 
the DOCUMENTER'S WORKBENCH Technical Discussion and Reference Manual. 

tbl is called a preprocessor because you use it to process a file before 
you use a formatter such as nroff. Like all preprocessors, tbl translates spe- 
cial words or characters into control lines that nroff or troff can use to pro- 
duce the final formatted document. You may use tbl with other preproces- 
sors, such as the equation formatting program eqn or the graphics format- 
ting program pic, or with macro packages such as mm, without duplication 
of function, since tbl only processes lines between the delimiters that it 
recognizes. 

After reading this tutorial, you will be able to prepare tables of varying 
degrees of complexity, and you will be able to read the "tbl Technical Dis- 
cussion" in the Technical Discussion and Reference Manual to learn more about 
preparing tables. 
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Formatting a Simple Table 



In the following discussion, <TAB> represents hitting the tab key once. 
If you have a file named newjengland that contains these lines: 




box; 
c c. 

State<TAB>Capital 



Hai2te<tAB>Augusta 

New Hamp6hire<TAB>Coa:ioo9xl 

Verniont<TflB>McDntqpelier 

l^sacliusetts<TAB>Boston 

Rhode Island<TAB>Provide9ioe 

Oc3rmecticut<TAB>Kartford 



typing either of these command lines 

tbl -TX newjengland | nroff -mm -Tip | col > new_england.tbl 

or 

mm -t -Tip new_england > new_england*tbl 

will produce a file called newjengland.tbl, which should look something 





like this: 



State 



Capital 



Maine 



Augusta 
Concord 

Montpelier 
Boston 

Providence 
Hartford 



New Hampshire 



Vermont 



Massachusetts 
Rhode Island 
Connecticut 
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Formatting a Simple Table 



The page number appears at the top of the page if you use the mm com- 
mand line, but it does not show up if you use nroff without mm. Otherwise 
the results should be the same. 

Do not worry about the tbl option -TX, which is useful when you pro- 
duce a table on particular kinds of printers. The "tbl Technical Discussion" 
in the Technical Discussion and Reference Manual describes -TX in detail. 

If you look at the output for this and later examples on a terminal 
screen or a typewriter-like printer, it might appear slightly different from 
this phototypeset page. You might see more space between the lines of text 
and the dark horizontal line that extends the width of the table (more about 
this line later), and you might notice a line of space after the last text line. 
These minor differences occur because terminals and printers produce nroff 
output and this page is a product of troff, which handles spacing 
differently. 

If new_england.tbl does not look right for reasons other than spacing, 
you might need to select another argument for the terminal (-T) option to 
nroff —mm or to mm. Ask your system administrator what to use, consult- 
ing the mm(l) or nro£f(l) manual page in the Technical Discussion and Refer- 
ence Manual for a list of the valid terminal arguments. 
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Table Delimiters 

The macro pair .TS and .TE delimits the section of a file that tbl inter- 
prets. With newjengland this means the entire file, but they can also del- 
imit a part of a larger file, such as a letter or a report that you are format- 
ting with mm macros. For example. 

Here are the New Qoglaxvi states and their capital cities. 
.D6 
•TS 
box; 
c c. 

State<EAB>Capital 

Maiiie<Dffi>ita3gusta 
New HBsqpshire<TAB>OGXico!Cd 
Vei3iDn[t<TAB>Montpelier 
Ma8sa<±usetts<TAB>Bo3ton 
Rhode l8land<TAB>Provideiice 
Oonnecticat<TAB>Kartford 
.TE 
.DE 
.P 

\ OSie largest of these capitals is Boston* . . . 



If you include tables that are less than a page long in a document that 
you plan to format with mm, it is a good idea to put each table in a display, 
that is, to surround the table delimiters (.TS and .TE) with .DS (or .DF) and 
•DE so that a page break does not divide the table when it is printed. The 
"mm Technical Discussion" in the Technical Discussion and Reference Manual 
elaborates on producing tables in mm documents. 
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Global Options and the Format Section 



After .TS you can specify global options that will affect the entire table. 
In newjengland, the only global option is box, which tells tbl to enclose 
the whole table in a box. Suppose that you want the table to be printed in 
the center of the page as well as enclosed in a box. Change the option line 
to look like this: 

box center; 

The order of global options does not matter, so center box; will do the 
same thing. 

A semicolon (;) ends the list of global options, and tells tbl that what 
follows is the format section, which specifies how each column in the table 
will look. 

In the file new_england, the format section contains one line: 
c c. 

The format section consists of key letters that tell tbl how many columns 
there will be and how each column is to be formatted. Here, the two 
columns of newjengland are centered, but if you want to left-justify the 
first column, you would change the format line to look like this: 

1 c. 

Notice that in new_england there is only one format line for all seven 
lines of data or text, tbl applies the last (in new_england, the only) format 
line in the format section to all the remaining rows of a table. Notice that a 
period (,) ends the format section; more about this later. Below is an exam- 
ple that shows how you can control the format of each line in the table. 
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Global Options and the Format Sectlpn 




center box; 



c c 
c 1 

i c 
1 1, 

State<TAQ>Capital 

Maixte<TAB>Augiista 

New Haiipshire<TAB>Coaicorti 

VeriB3nt<TAB>HQntpelier 

Massachus^tts<TAB>BostGn 

Rhode Islaiid<TAB>Provi<ieiice 

OoraiectiCTit<TAB>Hartford 

X_ J 

The formatted output looks like this. 



State 


Capital 


Maine 


Augusta 


New Hampshire 


Concord 


Vermont 


Montpelier 


Massachusetts 


Boston 


Rhode Island 


Providence 


Connecticut 


Hartford 



As you can see, tbl centers both columns of the first data line, 
State<TAB>Capital, centers the first column and left-justifies the second 
column of the second line, left-justifies the first column and centers the 
second column of the third line, and left-justifies both columns of the 
fourth and following lines. 

Suppose that you wanted to change the typeface of column entries: 
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Global Options and the Format Section 




box; 
cB cB 
c II 
1 cl 
1 II. 

State<TAB>Gapital 

f^diie<iiAB>Augusta 

New Kaiiip6hire<TAB>Oonoord 

VeiiDant<BAB>MDaitpelier 

Massachuset±s<TAB>Boston 

Fhode Islaijd<TAB>Priovidence 




Follow a key letter by B or b for bold, or I or i for italic to change the 
typeface of that column. Here is how the typeface changes above look: 



State 


Capital 


Maine 


Augusta 


New Hampshire 


Concord 


Vermont 


Montpelier 


Massachusetts 


Boston 


Rhode Island 


Providence 


Connecticut 


Hartford 



A period after the last key letter signifies the end of the format section, and 
that text is next. 
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More About Options and Format 

As the tables above illustrate, tbl looks for tabs to distinguish one 
column from the next. Keeping track of manually inserted tabs in small 
tables like newjengland is not troublesome. You might have trouble, 
though, aligning columns in larger tables that contain tabs. The table of 
U.S. Presidents below shows that tbl allows you to substitute other charac- 
ters for the tab. 




tac tab(;); 
c s s s 

C I C I C I c 

1 I 1 I 1 I 1. 

American Presidents 



Nane ; Paurty ; Term; ElectdGn-'OiipGnen^ 

Fraxilclin D. Itoosevelt;DGEC)cratic; 1933-1945; 1932-Hcx7ve^ 
;;; GtaiBS 

; ; 

;;;1936-LazKkin 

; ; ;_ 

;;;1940-WUIkie 

» » ;_ 

; ; ; 1944-Dewey 

Kaxxy S. Tc«nan;Denocxatic; 1945-1953; 1948-Dewey 
; ; ; IhuziDoaxl 
; ; ; Wallace 

IXd^^ D. EisenhCMer;Republican; 1953-1961 ;1952-Stevenson 



; ; > 




Notice the options line. The option tab(;) tells tbl to translate any semi- 
colon that it finds between the table delimiters into a tab character. Use 
any non-alphanumeric character as the tab character, for example, 

tab(#); 
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More About Options and Format 



Also notice a heretofore unexplained key letter in the format section, 
the letter s. This letter tells tbl to span the entry from the previous column 
across this column. Thus in the output shown below, tbl has centered the 
title American Presidents across the full table. 

Notice that the format section contains bars separating key letters: 

c ! c ! c ! c 
1 I 1 I 1 ! 1. 

When you put bars in a format line, you tell tbl to separate columns with 
vertical lines. If you put two bars between a pair of key letters, tbl 
separates those columns with a vertical double line, but only if your output 
device has the resolution to create it. Many printers that nroff supports do 
not have this resolution. 

Notice too that some lines of text are separated by the underscore char- 
acter: 

; ; ; Wallace 

Dwight D. Eisenhower ;Republican; 1953-1961; 1952-Stevenson 
» ! t_ 

Here, as in the new_england example, tbl translates an input line that con- 
tains only the underscore character (J into a single line extending the full 
width of the table. When the underscore character is the only text in a 
column, as in the fourth column in the line below Dwight D. Eisenhower, 
tbl extends the line through only that column. Since there is no text 
between the semi-colons (tab characters) marking the first, second and third 
columns, those columns are empty. This shows how using a tab character 
instead of a tab makes table source files easier to read and change. 

tbl does a similar chore when it sees the = character, creating requests 
for a horizontal double line the width of the table or the width of the 
column, as appropriate. As with the vertical double line, most printers that 
nroff supports do not have the resolution to create a horizontal double line. 
Unless you have access to a phototypesetter and to troff, you probably 
should not use this character or the vertical double line. 

In this example, there are three manually inserted spaces between the 
tab character and some column entries (for example, ;;; Wallace). This inser- 
tion is cosmetic, and entirely up to you. 
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More About Options and Format 



Here is the table of U.S. Presidents after it has been formatted: 



American Presidents 


Name 


Party 


Term 


Election-Opponents 


Franlclin O Roospv<*lf 




1933-1945 


1 9^2-Hoover 

Thomas 
1936-Landon 
1940-Willkie 
1944-Dewey 


Harry S. Truman 


Democratic 


1945-1953 


1948-Dewey 
Thurmond 
Wallace 


Dwight D. Eisenhower 


Republican 


1953-1961 


1952-Stevenson 
1956-Stevenson 



In a tbl table, you must always include a format section and text; 
options, of course, are optional. To learn about the full complement of 
options and key letters available, read the "tbl Technical Discussion" in the 
Technical Discussion and Reference Manual, 
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Text Blocks 



tbl makes each column slightly wider than the longest line of text that 
appears in the column. In the table of Presidents, the column containing 
Presidents' names was expanded to accommodate the name Dwight D. 
Eisenhower, the longest naihe in that column. 

However, there may be times when you want to compress more than 
one input line into a single column of output. You could break up a text 
block into separate lines, as was done in the Election-Opponents column in 
the previous table. But tbl gives you the power to fill columns more 
densely with the text block delimiters T{ and T). Suppose you wanted to 
add a biographical blurb to the table of Presidents. 
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Text Blocks 




box tab(;); 



c s s s s 

c I c I c I c I c 

1 I 1 I 1 I 1 I 1. 

^^merican Presidents 

Name ; Party; Term; Electian-<]ppQaients ; Notes 
T{ 

D. Boosevelt 

T} ;Deinocxatic; 1933-1345;T{ 
1932-Hcx>ver 

IhCDBS 

.hr 

1936-Lancbn 
.br 

1940-Willkie 
.br 

1944-Dewey 
T};T{ 

Inaugurated 
the "New Deal" 
and led the 
nation during 
Mbrld War II 
T} 




Do not put the text within the text block on the same line as the block- 
begin delimiter T{, and do not put any spaces or characters after this delim- 
iter. The block-end delimiter T} must always appear first on its line. Addi- 
tional columns of text may follow T} after you type a tab or tab character on 
the same line. If you do not specify the line length or the column width, 
tbl calculates the length of the text block as a function of the current line 
length, the number of columns in the table and the length of the longest 
line in the text block. Because this calculated length may be greater than 
some short lines in the text block, use the .br request (see "The Formatter 
nroff" in this guide) as specified here, to ensure that input lines do not 
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— Text Blocks 

overlap on output (for example^ to ensure you do not get 1932-Hoover and 
Thomas on the same line). 

See the last section of this tutorial for a complete example of text blocks 
in a table. 
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Line Length and Column Width 



You can change the column width of tables if you choose. Use the 
hroff request .11 to set the line length. Set column width with the tbl key 
letter w in the format section: 

c s k s s 

C I C i C I C I C 

Iwdi) I 1 I 1 I 1 I lw(1i). 

W sets a minimum column width; if the longest line in a column is wider 
than the valiie you specify after w, that longest line's width overrides the 
value. That is, w allows you to gain space around the text in a given 
column. In the format section specified above, the first column is at least 
one inch wide; the second, third, and fourth are at least as wide as the wid- 
est line of text; and the fifth is the same as the first. If you do not specify 
units (for example, inches), width defaults to ens. One en is about the 
width of the lower-case character n. 
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Troubleshooting 



If you want to check a table before printing it (using the UNIX Operat- 
ing System only), the command line 

tbl filename >/dev/null 

throws away the output, but prints any error messages that occur. 

The program checkmm checks whether every .TS has a matching .TE. 

If you forget .TS, or accidentally delete it, the formatter treats tbl con- 
trol lines as if they were ordinary text, printing options, the format section, 
and text in one jumble. If you forget to put .TE at the end of a table, the 
formatter includes all input lines until the end of the file (or all lines it 
encounters until another instance of .TE is read) in the table. That the for- 
matter is this forgiving may lead to strange output. 

Remember, global options are optional, but the format section and table 
text are mandatory. If you want to format tables that are longer than one 
page on output, beware of long text blocks. Text blocks that span two pages 
behave unpredictably. If you require long text blocks, break them up into 
contiguous sub-blocks. For more details about multi-page tables, see the 
"tbl Technical Discussion" in the Technical Discussion and Reference Manual 
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An Example: Including Text Blocks in a Table 



To format the table that follows, type: 

tbl -TX filename \ nroff -mm -Tip | col 

or 

mm -t -Tip filename 

where filename contains the following input. You may direct output to a 
file, or to a terminal or printer. 
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An Example: Including Text Blocks in a Table 



input: 





.TS 

box tab(;); 



c s s s s 



C I C I C I C I c 

1 I 1 I 1 I 1 ! 1. 



Postwar American Presidents 

Name ; Party ;Term; Electicn-Gppits ;NQtes 

T{ 

Harry 
S. Tnntan 

T} ;DeEDOcratic; 1M5-1953;T{ 
1948-Dewey 

Thurncnd 

H. Wallace 

T};T{ 

Led nation 
during 
Korean War 



T{ 

Dwi^it 

D. Eisenhower 

T} ;Republican; 1953-1961 ;T{ 

1952-Stevenscn 

1956-Stevenscn 

T};T{ 

Presided over 
ecQncroic boGm 
of the 1950s 
T> 

T{ 

John 

P. Kennedy 

T} ;Democratic; 1961-1963; 1960-Nixan;T{ 
Youngest can 



T} 





THE PREPROCESSOR tbi 17 



Text Blocks in a Table 
input continued: 



elected to the 

Presidency 

T} 

T{ 

Lyndon 
B. Johnscn 

T} ;DgnpcTatic; 1963-1969; 1964-Goldwater;T{ 
Architect of the 
"Great Society" 
T} 

T{ 

Richard 
M. Nixon 

T} ;Republican; 1969-1974;T{ 
1 968-'HuiQ[]hrey 
G. HEdlace 

.br 

1972-McGcvem 
T};T{ 

First President 
to resign 
T} 

T{ 

Gerald 
R. Ford 

T};Republican; 1974- 1977 ;Never elected;T{ 
Became V«P, vihen 
Agnew resigned 
T) 

T{ 

Jiimy 
Carter 

. T) jDemocratic; 1977-1981 ; 1976-Ford;T{ 
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Text Blocks in a Table 



input continued: 



Negotiated 
Canp David 
Acoocrds 
T} 

T{ 

Ronald 



T} ;Repi2blican; 1981-;T{ 
1980-Carter 
Anderson 

.hr 

1984-Mcsxaale 

T};T{ 

Oldest 

President 

T} 
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Text Blocks in a Table 
output: 



Postwar American Presidents 


Name 


Party 


Term 


Election-Oppnts 


Notes 


Harry S. 
Truman 


Democratic 


1945-1953 


1948-Dewey 
Thurmond 
H. Wallace 


Led nation 
during 
Korean War 


Dwight D. 
Eisenhower 


Republican 


1953-1961 


1952-Stevenson 
1956-Stevenson 


Presided 
over 

economic 
boom of the 
1950s 


John F. Ken- 
nedy 


Democratic 


1961-1963 


1960-Nixon 


Youngest 
man elected 
to the 
Presidency 


Lyndon B. 
Johnson 


Democratic 


1963-1969 


1964-Goldwater 


Architect of 
the "Great 
Society" 


Richard M. 
Nixon 


Republican 


1969-1974 


1968- 

Humphrey 

G. Wallace 
1972-McGovern 


First 

President to 
resign 


Gerald R. 
Ford 


Republican 


1974-1977 


Never elected 


Became V.P. 
when 
Agnew 
resigned 


Jimmy Car- 
ter 


Democratic 


1977-1981 


1976-Ford 


Negotiated 
Camp David 
Accords 


Ronald 
Reagan 


Republican 


1981- 


1980-Carter 

Anderson 
1984-Mondale 


Oldest 
President 
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Introduction 



This tutorial is intended to give you a working knowledge of troff, the 
DOCUMENTER'S WORKBENCH Software formatter for typesetting text. It 
will, in addition, introduce you to troff's programmable features. 

You should be familiar with the following concepts and tools to benefit 
fully from the pages ahead: 

■ You should know how to use a UNIX system text editor (ed, 
vi, and ex are examples). See the UNIX System V User Guide, 

■ You should know what a file and directory are and know 
how to manipulate them. See the UNIX System V User Guide. 

■ You should be familiar with nroff, troff 's close relative. See 
the tutorial in this guide, "The Formatter nroff 

■ Your understanding of troff would be assisted by a 
knowledge of the mm macro package though it is not essen- 
tial. See the tutorial in this guide, 'The Macro Package mm." 
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Basics 



The control of text you have seen with nroff takes two things for 
granted: first, that the size and typeface of individual characters will not 
change and second, that the final printed output will appear in neat, paral- 
lel lines of evenly spaced text, reading from left to right. 

nroff expects its output to follow the beaten paths of the typewriter car- 
riage. While nroff output can be printed on more advanced devices such as 
phototypesetters or laser printers, it is primarily intended for simpler dev- 
ices such as dot-matrix and daisy-wheel printers, nroff retains the sort of 
detailed control allowed by a typewriter: Tabs, margins, line spacing, and 
the rest can be set and reset. Yet, nroff offers programmable features as 
well. 

nroff's near relative, troff (TEE-roff), also offers a detailed control of the 
text. While you still have almost all nroff's capabilities, you also have in 
troff the power to shape the characters themselves, troff frees your text 
from the limits of mechanical printing and introduces it to digital typogra- 
phy. Characters can be enlarged or shrunk to a variety of sizes. Text can be 
changed into diverse shapes by choosing from a library of typefaces (such as 
Helvetica and Greek) and special characters (such as left and right hand 
signs and mathematical symbols). 

With its requests and escape sequences, troff closely resembles nroff. 
The troff command line shown here is similar to command lines in nroff: 

troff my.file | typesetter 

Like nroff, troff is easy to use. But in its simple requests and escape 
sequences lie considerable power and capacity for fine-tuning, troff's range 
includes all of the page, the ability to combine existing characters to make 
new ones, and the power to place those characters anywhere. 
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Fonts and Special Characters {.it and \f) 



Unlike nroff, which is primarily intended for producing typewriter- 
quality output, troff can present its output in a variety of typefaces, or fonts. 
The font request, .ft, accepts both alphabetical and numerical arguments 
with which to specify particular fonts. The actual range of fonts troff will 
produce depends on what printer you are using and the device programs 
(or drivers) supporting that printer. 

You can change fonts with the request .ft, followed by an argument that 
names the font. Consider these examples of input and output. First the 
input: 




This line is italic, 
.ft R 

This line is ronen. 




And now the output: 

This line is italic. 
This lirife is roman. 

The alphabetic argument— here / for italic and R for roman — mnemonically 
recalls the font it specifies. The argument P means previous font and will 
instruct troff to print all characters following .ft P in the font that preceded 
your last specification. The .ft request with no argument is identical to .ft 
P, telling troff to revert to the previous font. 

The number of troff fonts is effectively increased by the request .bd 
(embolden). This request will further embolden any non-bold character and 
make any bold character even bolder. As with many troff requests, the 
fine-tuning is in your hands, .bd requires specifications of both font and 
width of boldness: 

.bd F W 

So, if your printer does not already provide emboldened italics but does 
provide italics, you can devise your own with .bd. Here is the input you 
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Fonts 



would use: 





.bd 2 3 
.ft 2 



Hiese characters are printed in 
italics that has been entoldened. 
.bd 2 





And here is the result: 

These characters are printed in italics that have been emboldened. 

You may wonder what the arguments following .bd mean. The 2 
specifies the font position at which the italic font is loaded, position two. 
The second argument, 3, specifies the width of the emboldening. The .bd 
request works by forcing the printer to back up a specified number of units 
from the place where a character was initially printed to plot it again at a 
slight offset. You determine that offset with the second argument, in this 
case, 3. Any font, consequently, can be emboldened. Light fonts, such as 
the italic fonts, can be given greater weight and prominence, and bold fonts 
can be made even bolder. As the example shows, you turn off the embol- 
dening request by typing .bd without the second, numerical argument. 

To this point you have learned how to control fonts using requests. In 
fact, every possible font change can be made using requests. You may find, 
however, that requests are sometimes awkward. Making several font 
changes in a single line or phrase, for example, is inconvenient with a 
request. Therefore, troff permits you to choose fonts in a variety of ways. 
Making a font change with an in-line request, or escape sequence (so called 
because it contains the escape character) would be easier. An input line 
such as 

\flltalic runs. NfRRonan antbles. NfBBold plods. 



Italic runs. Roman ambles. Bold plods. 

Notice that the font escape sequence, like other escape sequences, produces 
no output space. So if you want space, be sure to add it. 



produces 
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Fonts 



While not all printers offer the full catalog of fonts, all devices support- 
ing troff provide at least three fonts: roman, italic, and roman bold. These 
are frequently mounted at the first three font positions: 

1 roman 

2 italic 

3 roman bold 

Using these numbers, you can pose a numerical argument to a font 
request or escape sequence instead of an alphabetical one. The example 
given earlier might have been typed as follows: 

\f2Italic runs, \f iRonan ambles. \f3Bold plcxis. 

Alternatively, it might have been specified with the .ft request: 




Italic runs, 
.ft 1 

Raman aznbles. 




What is the point of using this numerical method? It makes revision, i 
especially on a large scale, easier. Suppose you decided to change all your 
italic words to bold and all your bold to italic after having completed a long 
report. You could change your input using a text editor. On the other 
hand, you could leave the input alone and simply load bold at position two 
and italic at position three using the .fp (font position) request: 

.fp 2 B 
.fp 3 I 

Saving time and ensuring comprehensive precision, you've made the switch 
from bold to italic and from italic to bold. 

With this ability to load fonts you can determine the default of a 
document's typefaces. If you had, for example, loaded italic at the first posi- 
tion, the document's predominant typeface would have been italic. The 
number of fonts at your disposal depends on your printing device. 
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Fonts 



Mounting Fonts (.fp) 

troff can mount as many fonts as your printer will allow. That is, if 
your printer only permits four fonts to be present at any one time, troff will 
load four. But troff also makes the printer-imposed limit somewhat painless 
since it gives you the capacity for mounting more as needed. Of course, if 
the printer has only four fonts, troff's flexibility in this respect is irrelevant. 
You can benefit from this feature using the request you learned in the last 
paragraph, the font position (.fp) request. Your selection of fonts may be 
quite large. The Autologic APS-5 phototypesetter at AT&T Bell Labora- 
tories, for example, provides over thirty different fonts including the fol- 
lowing: 



R 


Roman 


/ 


Italic 


B 


Bold 


S 


Special (i^ / O) 


BI 


Bold Italics 


C 


News Gothic Condensed 


CE 


Century Expanded 


CI 


Century Bold Italic 


cw 


Constant Width 


CT 


Courier Typewriter 


GR 


Greek (a y) 


®© 


®errnan ©cript 


H 


Helvetica 


HB 


Helvetica Black 


HI 


Helvetica Italics 


PA 


Palatino 


PB 


Palatino Bold 


PI 


Palatino Italics 


FX 


Palatino Bold Italics 


SI 


Special 1 




SftmfU 


SM 


Stymie Medium 


TB 


Techno Bold 
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Fonts 



As you can see, many fonts can be used in even a single paragraph. 
You cannot, however, use them at random, troff is able instantly to apply 
whatever fonts your typesetter has, but many typesetters have a limited 
number of font positions. Your typesetter might only have four positions at 
which to mount fonts. In this case each must be mounted using .fp and its 
appropriate argument. If the list above had been printed on a typesetter 
limited to four font positions, you would have used the following method 
for stating your input: 




•rp 1 o± 




.fp 2 C 




.fp 3 CE 




• ft HI 




BI 


Bold Italics 


.ft C 




C 


News Gothic Ccandensed 


.ft CE 




CE 


Century Bcpanded 


.fp 1 CI 




.fp 2 CW 




.fp 3 CT 




.ft CI 




CI 


Century Bold Italic 


.ft CH 




cw 


Coistant Width 


.ft cr 




CT 


Courier Typewriter 


.fp 1 GP 




.fp 2 GS 




.ft GP 




GP 


Greek (\(*a \{*h \(*g) 


.ft GS 




GS 


Gernen Script 



And so forth. As each new set of four fonts is about to be used, they are 
first mounted. 
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Fonts 



It is best not to remount another font where the Special (S) font had 
been in any single processing run of text. Ask your system administrator 
where the Special font is mounted. 

Naturally, when you are finished using a relatively rare font, it is good 
practice to set things back to default: 

.fp 1 R 
.fp 2 I 
.fp 3 B 

As you can guess from what has been said, once each font is mounted 
you can invoke it by number as well as by letter(s). Courier Typewriter 
above, for example, could have been specified with .ft 2 or \f2 as well as 
with the request, .ft CT, or the escape sequence, \f(CT. 

What happens when you ask for a font that has not been mounted? 
troff will automatically attempt to mount such a font at position 0. Because 
the zero position is reserved for this dynamic arrangement, you are not per- 
mitted manual access to it as you are to the other positions. Font position 
cannot be used for more than one font in a given line or diversion. 



The Font Macro 

In addition to using requests and escape sequences, the mm macro pack- 
age also provides macros to make font changes. These are limited to three: 
.R (roman), .1 (italic), and .B (bold). (The remainder of available font macros 
are made up of combinations of these.) Each, in fact, is an indirect way to 
use the .ft request. .R activates .ft 1; .1 activates .ft 2; etc. Each macro thus 
produces whatever font is loaded at its corresponding numerical position at 
the time it is used. If Helvetica had been mounted at position three, then .B 
would produce Helvetica, not emboldened roman. 

Other font macros are .RI, .RB, .BI, .BR, .IR, and .IB. Each, as its name 
suggests, is a combination of the primary fonts: roman, italics, and bold. 
An intervening space between words or characters tells the macro when to 
switch fonts. Here is a typical input line: 

.HI bold italic. 

And now the output: 
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Fonts 



holditalic. 

Notice that the space between the words has been closed by the macro. To 
leave a space or spaces, enclose the word(s) and space(s) in double quotes, 
for example: 

.BI "bold " italic 

These macros can be handy. You can use them conventionally, placing 
them on the line that precedes the text you want to change. The following 
is input: 

.1 

Like .ft I, the .1 macro prodaces italic print. 
.R 

And now, the output: 

Like .ft /, the ./ macro produces italic print. 

Like the .ft I request, you need to specify the change back to roman. 

These macros can also be used on the same line as the text. This usage 
does not require a return to the previous font. By placing them on the same 
line as the text you want to modify, you set up an automatic return by 
default. The input looks like this: 

.1 "Used this way, these macros change font for one line only." 
.br 

The next line automatically reverts to the default font, roran. 

The outputshows that the shift to italic occurs only in the line on which 
you place the macro: 

Used this way, these macros change font for one line only. 

The next line automatically reverts to the default font, roman. 

Note that the double quotes given on the input line do not appear on 
the output line. This is a convention of nroff and troff macros when they 
appear on the text line. If the macro is followed by a single word (a 
sequence of characters not interrupted by white space), no double quotes 
are necessary. If the macro is followed by more than one word, it is neces- 
sary to enclose the phrase with double quotes. Thus, these mm macros are 
limited to one input line of contents, though the line could be extended by 
wrapping it instead of pressing RETURN. 
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Point Size (.ps and \s) 



The many fonts troff is capable of loading usually come in a variety of 
sizes, which can be selected with the requests and escape sequences that 
control point size. You control point size with the request •ps, or with the 
escape sequence \s, both of which adjust the height and width of your char- 
acters. (The point size refers to the size of the block on which the character 
is plotted, so individual characters are usually smaller than the measure 
specified.) 

Like the number of fonts available from typesetter to typesetter, the 
range of troff's point sizes is device-dependent. The span of available sizes 
found on most devices ranges from six point (one-twelfth of an inch) to 
thirty-six point (one half an inch). But you can usually expect more. There 
are fifteen sizes in the following list: 



6 point 

7 point 

8 point 

9 point 

10 point 

11 point 

12 point 
14 point 
16 point 
18 point 



20 point 
22 point 
24 point 

28 point 

36 point 



As you can see, in the instances where a point size is skipped, you will usu- 
ally get the nearest available point size. The following, for example, is a list 
of illegal sizes and their assigned replacements from a machine whose 
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Point Size (.ps and \5) 



characters range from three point to forty-eight point: 



1 *> 




71 
Zl 






* zz 




— » 74 
^ Z4 


Z/ 


— * 7/1 

^ Zo 


70 


— » 7Q 

* Zo 




^ ^n 




32 


35 


34 


37-38 


^ 36 


39 


40 


41-42 


— 40 


43 


44 


45-46 


^ 44 


47 


48 


49- 


48 



This reassignment of point size is typical of the UNIX system's behavior. 
Rather than quitting when it sees a command that is impossible to fulfill, 
troff gives you a reasonably close substitute. In most cases, as the present 
example illustrates, you get one that is one seventy-second of an inch 
smaller. 

The .ps request accepts only numerical arguments. You would set text 
in twelve point characters as follows: 




IWelve point is surprisingly 
larger than default point size, 
.ps 10 



Twelve point is surprisingly larger than default point 
size. 




And here is the output: 
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Point Size (.ps and \s) — • — 

Notice the symmetry. Without an accompanying request specifying a return 
to the default point size (usually ten point), all succeeding text would have 
been set to twelve point. 

You can also specify point size with the escape sequence \s. Like the 
font escape sequence, the size escape sequence is immediately followed by 
an argument. The arguments themselves are identical to the ones you 
would use with requests. That is, the numerical argument is identical to the 
point size you want: 

\s10TEK\s15FIPIEEJr^^2(m«®n^ 

gives you 

tenFIFTEEnTWENTY 

Again, notice the return to default: ten point. A succession of twenty 
point characters would catch your attention but would require a good deal 
of page turning. You will also notice that the escape sequence itself occu- 
pies no space on the output line. 

There are circumstances in which you would not want to specify point 
size literally. A given document, for example, might be destined to be 
printed using two different ranges of point sizes. Let's say one was to be 
printed using twelve point for readers with poor eyesight while a second 
printing was to be in nine point. To preserve proportion with each docu- 
ment, you might have to face a complicated editing effort. But if the point 
size changes you had made within each document had been relative 
changes, printing one document in two different point sizes would be easy. 
You accomplish relative changes using expressions instead of integers for 
arguments: 

DEFAULT \s+4DEFAULT + 4 \s+4DKFAULT + 8\s-8 
gives you 

DEFAULT DEFAULT + 4 DEFAULT + 8 

The point size escape sequence, VsO, means "return to the previous point 
size" and allows you to maintain a relative set of point size requests. Thus, 

TEN \s+9NINE?rEEN \sOTBN 

would produce 
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Point Size (.ps and \s) 



TEN NINETEEN ten 



Vertical Spacing (.vs and As) 

troff characteristically offers a great capacity for fine-tuning. It was 
expressly designed to give you precise control over your text, and point size 
is no exception. As individual characters are subject to your control, so the 
spacing between lines of characters is available for your adjustment. 

This companion parameter to point size is .vs, the vertical spacing 
request. Its numerical argument specifies the vertical spacing, or leading, 
between pairs of successive lines. Usually, you set vertical spacing to be 
about twenty percent larger than the character size. "Nine on eleven" (nine 
point characters and eleven point spacing) or "ten on twelve" (troff's default 
value) is conventional. 

That is, 

.ps 9 
.vs 11p 

would give us text 

that looked like this. 

But if we were to change to 

.ps 12 
.vs 14 

the result would be markedly different. 
Point size and vertical spacing 
change substantially the amount 
of text per square inch. 

.ps 6 
.vs 7 

would really drive the point home, though. 
For example, ten on twelve uses about twice 
as much space as seven on eight. This is six 
on seven, which is even smaller. 
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Point Size («ps and \s) 



It certainty 

gives you lots of infonnation per page^ 
but decreasing point size 



.ps 5 

.VS 6 



could otake your reader 
believe that he or ihe 



.ps 4 
.VS 5 

When used without arguments .ps and .vs revert to the previous value. 

The command .sp is also used to get extra vertical space. It does not set 
the amount of space between all lines of characters as .vs does. Rather it 
specifies the number of spaces you want at a given place in the text. Con- 
sider this usage; 



An input line like this 
.sp 1 

will give you one space 
cxr 'bro spaces 
.sp 2 

depending on your needs. 



The output appears as 

An output line like this 

will give you one space 
or two spaces 



depending on your needs. 
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Point Size (.ps and \s) 



Unadorned, .sp gives you one extra blank line (one vertical space, what- 
ever ,vs has been set to). If that's not what you want, .sp can be followed 
by information about how much space to leave: 

.sp 2i 

means "two inches of vertical space." 

• sp 2p 

means "two points of vertical space." Finally, 

• sp 2 

means "two vertical spaces"— two of whatever .vs is set to. (This can be 
made explicit with .sp 2v.) troff also understands decimal fractions in most 
request arguments, so 

.sp 1.5i 

is a space of 1.5 inches. These same types of measures (inches, points, and 
spaces) can be used after .vs to define line spacing and, in fact, after most 
commands that deal with physical dimensions. 

In the same company with .vs and .sp is .Is (line spacing). .Is is typi- 
cally used at the beginning of a document or block of text to specify the 
number of vertical spaces between successive pairs of lines. By default this 
number is one. The numerical arguments it accepts determine the ratio of 
single blank lines per lines of text. The argument itself is a total of space 
lines and text lines. Thus, .Is 2 represents the sum of one line of space plus 
one line of text. .Is 3 will give you two spaces for every line of text, and so 
forth. .Is is not a replacement for .sp. It sets the default value for line spac- 
ing, .sp may still be used at any time to specify a particular line spacing. 

It should be noted that all size numbers are converted internally to 
"machine units" (whose ratio to inches varies from machine to machine). 
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Local Motions 



Moving further from the carriage rows of a typewriter, troff will let you 
depart, at a moment's notice, from the place where your next character was 
to be struck, to a remote part of the page. This local activity of movement is 
called local motions. Although you might expect such a radical departure 
from the norm to require elaborate arrangements, local motions are done as 
font and point size changes are: with a escape sequence. 



Vertical Motion (\v) 



Consider using vertical motion, for example, to lift and lower individual 
characters and words: 



Down 



Stat 



The baseline (the line unchanged by vertical motion) is the line where 
"Down" is sitting. 

You can elevate or lower characters with one escape sequence, the \v. 
To move the word "Up" downward, you simply precede it with the escape 
sequence together with directions for the distance you want "Up" to travel: 

\v'+1'Hp 

This says, in effect, move down (a positive direction in the world of 
forward-moving text). As you might imagine, all words following the verti- 
cal motion escape sequence will also be elevated or lowered at precisely the 
level dictated by the escape sequence. To return to the initial vertical posi- 
tion, simply give the opposite escape sequence argument: in this case 
\v -1'. The next word from the example, "the," is preceded by \v -0.5', thus 
moving back half the distance from the place where "Up" was printed. 
"Down"'s escape sequence, likewise, is \v'-0*5', bringing that word back to 
the baseline. The input line for these words looks like this: 

\v'+ruip \v'-0.5'the \v'-0.5'Down 

We could have substituted '1' for the argument '+!'. As is often the case in 
troff, arguments that increment or decrement assume "+" to be default. 
Only the explicit "-" will, in the case of \v, give you upward movement. 
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Local Motions 



Notice that the local motions escape sequence, \v, is similar to the font 
and point size escape sequences except for one thing. Unlike those near 
relatives, \v encloses its argument in single quotes (apostrophes). The 
numerical argument you give the \v escape sequence specifies units of .vs 
(whatever you set vertical spacing to). If vertical spacing is set to be one 
inch, then \v'-l' will move the characters following it upward a distance of 
one inch. 

An alternative to \v are the escape sequences \u, the up escape 
sequence, and \d, the down escape sequence. These do not have the range 
of \v, but their simplicity comes in handy for some commonly encountered 
words or expressions: 

Footnotes\uAd 
14\u\s610\sO\d 
Tradeinarks\u\s61M\sO\d 

for example, will give you 
7 

Footnotes 
I410 

Trademarks™ 

Notice the symmetry of troff usage. Like \v, which requires a compan- 
ion escape sequence to return to the baseline, \u and \d accompany each 
other: for every down there must be an up and vice versa (unless, of course, 
you don't want to return). The exponent and trademark examples are espe- 
cially interesting ones. At the center of the activity are the characters 10 
and TM waiting both to be elevated and shrunk by the escape sequences \u 
and \s6, respectively. All following characters, however, will remain 
elevated and reduced if 10 and TM are not followed by escape sequences 
bearing values opposing the initial settings. 

\sO is especially useful for local motions since you often do not care 
what the former point size is; you simply want to return to it. 
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Horizontal Motion (\h) 

At present, you have learned to travel the upward and downward corri- 
dors of a page. To move freely in any direction, you need the further capa- 
bility to move to the left and right. This you can do with the escape 
sequence \h. Like \v, \h requires arguments that are set off by single quotes 
(apostrophes) and are given with minus (— ) or plus (+) signs. The + will 
give you rightward movement (a positive direction in the context of troff 
output); the - will give you leftward movement. As with \v, + is default, 
and the omission of the + or — will be understood to be a positive, or right- 
ward, movement. Consider the following examples: Typing 

<Nh'-0.3m'> 
[\h'-0.2m'] 

will give you a simple diamond and rectangle, respectively: 
O 

D 

But 

<\h'0,^'> 
[\h'0.2m'] 

will spread these companion marks apart according to your numerical argu- 
ment: 

< > 
[] 

Notice that these arguments specify measures in ems (about the width 
of an m in whatever point size that applies at the time). The em is the 
default for the horizontally-oriented requests and escape sequences, and 
these escape sequences could have been expressed as \h'— 0.3' and \h'— 0.2', 
respectively. The \h escape sequence also accepts other measures including 
inches (in decimal fractions), picas, and machine units. 
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tsiOIH 



See the "nro£f/tro£f Technical Discussion" in the Technical Discussion and 
Reference Manual for an explanation of these measures. 



The additional use of point size (.ps) and en\boldening (.bd) will, of 
course, give you variations on these themes. While the preprocessor pic 
enables you to draw pictures, troff's ability to combine existing characters to 
make new ones can also be useful. 
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Consider the following example, which uses characters made by both 
horizontal and vertical motion: 

Hen Turnus in this finall fight downethrowne, his flittring 
ghost 

Had yeelded vp into y aire, in middest of all the host 
Aeneas valient victour stands, god Mauors chapion bold. 
The Latines stoynisht standing, from their hartes great groanes 
vnfold. 

And deepely from their inward thoughts reuoluing cause of care. 
Their daunted minds they do let fall 

The input for the first word of this passage looks like this: 

\v' 1 . 7 ' \s36\rsh'-0 • 5m'V\sO\v -1 . 7 'Hen 

The thirty-six point size of the W was incremented and decremented by the 
\s escape sequence. The more interesting aspect of this construction, 
though, is the drawing together of the two Vs with the \h escape sequence. 
The second V moved back toward the first a distance of two ems (at thirty- 
six point, remember) until they actually crossed and formed another charac- 
ter. The downward movement (\v'1.7') and opposing upward movement 
(\v'-1.7') was done to allow for space and to position the character grace- 
fully. The surrounding text was offset with the temporary indent request 
.ti 0.5i moving it horizontally a half an inch to the right. 

One character (it's actually a word) that probably caught your eye is the 
early English contraction for the: y . It is created using two unconventional 
features: horizontal and vertical motion and size change. To make y , we 
must reduce the size of the e and move it both slightly backwards and 
above the y. We determine size change by inserting \s before the character 
we want to alter. Thus, ye as a line of processed text would be accom- 
plished by typing y\s6e as a line of input. The y appears in the default 
point size, ten, and the e appears in point size six, dictated by \s6. 

We determine vertical motion, similarly, with the escape sequence \v. 
Thus, 

y\s6\v'-0.5'e 

will produce y*. We specify that e be moved up one-half of a unit. 
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Finally, we want to move the e to the left. 

y\s6\v'-0 . 5 '\h'-0 . 35m'e\h' . 35rti'\v' . 5 '\sO 

produces y . Again, notice that the amount of motion following \v and \h 
is conventionally set off by single quotes. 

As you have seen throughout these tutorials, the language of nroff and 
troff is one of graceful symmetry. In the example above, for every \s6, we 
must counterpose a \sO to cancel its predecessor. Otherwise, everything fol- 
lowing the initial point size change would be reduced to that specified 
change. Likewise, every \v'-0.5' must be followed with a countervailing 
\v'+0.5', and every \h '-0,35m' must be followed with \h'H-0.35m'. Thus, our 
y is formed by 

y\s6\v' -0.5' Nh' -0.35m' e\h' 0.35m' \v' 0.5' \sO 

Such a word is obviously too cumbersome to type every time we want 
to produce so brief a word as y . The solution, as the nroff tutorial shows, 
is to store it in a macro or string and call it with.yE or \*(yE. 

Finally, there are also several special-purpose troff formatting com- 
mands for local motions. \0 is an unpaddable white space of the same 
width as a digit. Unpaddable means that it will never be widened or split 
across a line by line justification or filling. There is also \ (backslash 
blank), which is an unpaddable character the width of a space; \|, which is 
half that width; \", which is one quarter the width of a space; and \&, which 
has zero width and is often used as the first character on a text line that 
begins with a dot (.), which otherwise would be read as a formatting com- 
mand. 

The escape sequence \o used like 

\o'set of characters' 

causes (up to nine) characters to be overstruck, centered on the widest. This 
is nice for accents, as in 

syst\o"e\*"ine t\o''e\'n\o"e\'"phcEnique 

which makes 

systeme telephonique 

The input for the accents are V and V, or \(ga (grave accent) and \(aa (acute 
accent). 
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You can make your own overstrikes with another special convention, \z, 
the zero-motion command. \z:c suppresses the normal horizontal motion 
after printing the single character x, so another character can be laid on top 
of it. Although sizes can be changed with \o, it centers the characters on 
the widest, and there can be no horizontal or vertical motions, so \z may be 
the only way to get what you want: in this case, a tunnel of squares. 

il 

is produced using the predefined troff escape sequence for making squares, 
\(8q. 

• sp 2 

\s8\z\ ( sq\s 14\z\( sq\s22\z\( sq\s36\( sq 
The .sp 2 is needed to leave room for the result. 

As another example, an extra-heavy semi-colon that looks like 

; instead of ; or ^ 

can be constructed with a big comma and a big period above it: 

\s+6^os,\v'-0.2&ti' Av'0.2an'\s0 

"0.25m" is an empirical constant. 

A more ornate overstrike is given by the bracketing function, \b, which 
piles up characters vertically, centered on the current baseline. Thus, we 
can get big brackets, constructing them with piled-up smaller pieces: 

{[^i- 

by typing in this: I 

\b' \(lt\(lk\(lb' \b' \(lc\(lf ' X \b' \(rc\{rf' \b' \(rt\(rk\(rb' 

In this case, the piled-up pieces are given in two groups on either side 
of the X, each delimited with a leading \b. The first forms a large, left-hand 
curly bracket: 

\(lt, or left top of curly bracket (f) 
\(lk, or left center of curly bracket {\ ) 
\(lb, or left bottom of curly bracket (0 

Following the \b as they do, they all must back-up to be overstruck. 



22 USBWS GUIDE 



Creating New Characters With Local Motion 



forming the curly bracket. The next group forms a left-hand square bracket: 

\(lc, or left ceiling of square bracket (f) 
\(lf , or left floor of square bracket ( f ) 

The groups to the right of the x simply form the right-hand counterparts to 
the left-hand curly and square brackets. The important thing these pieces 
have in common is that they are delimited by the \b with its associated sin- 
gle quotes and are therefore all subject to overstriking the other members of 
their groups. 

troff also provides a convenient facility for drawing horizontal and 
vertical lines of arbitrary length using arbitrary characters. \Vli draws a 

line one inch long, like this: The length can be followed 

by the character to use if the doesn't suit you. \rii/ will draw, for exam- 
ple, a one-inch line of dots: The construction \L is analo- 
gous except that it draws a vertical line instead of horizontal. 
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In the preceding tutorials you have seen the requests, escape sequences, 
and macros you need to produce a wide range of text formatting features. 
These formatting commands, concerned with page control, might be viewed 
as the surface of nroff and troff. They stretch and diminish indents, line 
lengths, page lengths, tabs, and the rest depending on the arguments you 
give each request or macro. 

The capabilities of nroff and troff, however, go beyond interpreting and 
carrying out your formatting instructions. They are able to store them, 
remember them, and use them again. What is more, nroff and troff can use 
arithmetic to evaluate and compute such stored information. This below- 
the-surface activity gives you something truly extraordinary in text process- 
ing: formatters that you can program. 

You might choose to ignore what goes on below-the-surface. This 
would be fine: you might simply build your own library of macros and 
escape sequences and not be troubled with the rest. If, on the other hand, 
you want to explore this new territory, it is there for the taking. 

Number Registers 

You have already read about number registers in the nroff tutorial in 
this guide. They are the storage places for various page values. The 
amount of indent, for example, is stored in a place called the .1 register. As 
you change the indent in the customary way (.in +li), the register .1 also 
changes. You cannot change the .1 register directly; it is a read-only register 
(unlike various others) and changes automatically according to the argu- 
ments you make to the indent request. Let's see how this works. 

You ask for the value of the register, whatever it is at the time, by 
preceding the register name with the characters \n for one-character register 
names and \n( for two-character register names. Thus, \n% would give you 
the value of the page number register, %, and \n(.l would find the value of 
the line length register (.1). Because the indent register is .i, we derive its 
value with \n(.i. If you set the indent to zero, the register value will be 
zero. A file that contains 

.in 
\n(.i 
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will yield an indent as far to the left as possible and the number 0. Let's 
see what happens to the .i register when we increment .in one inch. Typ- 
ing 

.in +li 
\n(.i 

in your input file would give you the following in your output: 
723 

You would get the number 723, the number of basic units 
for the APS-5 phototypesetter, and all succeeding text, as 
you can see, would be moved over one inch from the previ- 
ous left-hand margin. These basic units reflect the one-inch 
indent just made plus whatever indent is controlling this 
page at the time of printing. (The number of basic units for 
nroff is 240; units are typesetter-dependent for troff.) Typ- 
ing a simple .in will give you the previous indent. 

The fact that the value of registers is calculated in units need not 
interest you. What is interesting is that you can use arithmetic to find and 
use valuable information about any given page. 

Imagine, for instance, that you wanted to indent a block of text a dis- 
tance that would be proportionately offset no matter what the size of the 
page might be. A single, numerical incrementation naturally would pose 
problems. What would be indented one-fourth of a page to the right on a 
small page might be indented one-sixth the width of a larger page. Using 
the value of registers, however, we avoid this obstacle. If we added the 
value of the current line length (\n(.l) to the current indent (\n(.i) and 
divided the sum by four, we could find one-fourth the page width whatever 
the page's size might be. 

So that this device will be easier to use, let's define it as a macro and 
give it a name that identifies its function of indenting one-fourth of a page: 

•de i4 

.in( \\n(.i+\\n(.l)/4 

This macro definition (which you would place at the beginning lines of 
your document) is simply made of a request and one very long argument. 
The arithmetic expression used to define the macro would have been easier 
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to read had we used blanks (white space) to set off the expressions elements, 
nroff/troff arithmetic expressions, unfortunately, do not permit the use of 
white space. The parentheses are used to ensure that the addition of both 
the line length and the indent will be divided by four. 

Notice the double backslashes following the macro definition. Some 
backslashes between the .de request and its accompanying request must be 
protected by an extra backslash. The extra backslash in the example above 
delays interpretation of the register since the value of that register could 
change from the time the troff is copied to the time the document is 
printed. 

The input file would look like this. (Since this example demonstrates 
indentation, it has not itself been indented): 



OMs is namal text that should be subject to current line length 
and Indent values. 

That is, this text should be identical to the text that has 

preceded it on this tutorial page. 

.i4 

This block, hoMever, should be indented by a distance equal to 
twenty-five percent of the text preceding it. And all text 
following the \f3.i4\f 1 naczo should be similarly indented, 
.in 

Text follcwing the request for the previous indent should 
.bring thingrs back to nomal. 



The output file is next: 
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This is normal text that should be subject to current line length and 
indent values. That is, this text should be identical to the text that has pre- 
ceded it on this tutorial page. 

This block, however, should be indented by a distance 

equal to twenty-five percent of the text preceding it. 

And all text following the .14 macro should be similarly 

indented. 

Text following the request for the previous indent should bring things back 
to normal. 



These basic concepts — deriving the value of number registers and using 
arithmetic to compute those values— are important and constitute two basic 
techniques essential to advanced text programming. Be sure you under- 
stand them. 



NOflE 



You will find a complete list of number registers in the "nroff/troff Techni- 
cal Discussion" in the Technical Discussion and Reference Manual. 



Traps 

This tutorial will present two additional concepts that are frequently 
used in text programming: testing and conditional statements. The 
page trap is a rudimentary way of understanding and using both of these 
concepts. 

The need request (.ne) is, in effect, a simple page trap, .ne followed by 
a number (which represents a number of output lines) both tests data and 
conditionally responds to that data. Supposing it were important to print a 
block of text uninterrupted by page breaks, you would want to find how far 
from the page's bottom your text block might be. The .ne request would 
conduct that test and print the block if you had enough room or save the 
block for the next page if you did not. Because this material is covered ear- 
lier in the nroff tutorial, a brief example will suffice: 
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.ne 3 
.nf 

This block of text, \diich takes ^sp three output lines, 
cannot be separated, "nie ability to hold text together is 
especially inportant uhen ocmparing exanples or illustrating a point. 



If two lines of space remain on the page, this entire block will be printed, 
intact, at the start of the following page. 

The page trap is a more sophisticated version of the .ne request. Like 
the need request, the page trap tests data and responds conditionally. 
Unlike the need request, the page trap does more than print or fail to print. 

You set the page trap with the .wh (when) request. The first argument 
to .wh is either zero, indicating the top of the page, or a negative number, 
indicating distance from the bottom. The arguments are then followed by a 
request or macro you want to begin operation when you cross the trap. Con- 
sider the examples: 



.de hD \" define header 

'sp 1i \" space one inch 

\" end definition 
.de fO \" define footer 
'bp \" break page 

\" end definition 
.wh hD \" set top-of-page trap 
.wh -1i fO \" set bottcm-of-page trap 



You probably wondered why the macros .hD and .fO lacked dots in the 
page trap examples. These are macros whose names are given to .wh; they 
are not actual macro calls in this instance. 
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Because the examples in this section will become increasingly more 
complex, key lines will be followed by comments. Remember, comments 
preceded by A" or '\" are neither printed nor interpreted by the system. 

The preceding example emphasizes the latitude of the trap: where you 
can include one macro, by virtue of defining new macros, you can include 
any and everything. In this case, .hD and .fO are defined simply. When 
you get to the header (determined by the 0), output a one-inch space; when 
you get to within one inch of the page's bottom, break page. Notice that 
you are limited to one numerical argument per .wh request since these are 
to set page locations for springing their respective traps. 

Notice that the .sp and .bp requests, which normally cause a line break, 
begin with instead of to suppress the line break function. This is an 
important, if complex, part of setting page traps. Often in fill mode the out- 
put line that springs the trap is not neatly processed. Some word or part of 
a word might be squeezed out. Should that temporarily stray fragment 
meet up with a line break while going through a trap, it would be lost. The 
character suppressing that break function thus plays an important role in 
protecting such text. 



NOTE 



For a list of requests that force a line break, see the "nroff/troff Technical 
Discussion" in the Technical Discussion and Reference Manual, 



Defining macros with additional escape sequences, requests, registers, 
and traps can be used to accomplish a great deal of text processing: 
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.de hD \" define header 

sp I 0.5i 

.tl ' " \\n(nDA\n(dy/\\n{yr \\nX' \" give date and page nurnber 
sp 0,5i 




de fO 
sp 0.2i 



\" define footer 



,ps 12 
ft I 

,ce 1 



\" set title in twelve point 

\" set title in italic 

\" center title at the botton of each page 



IXitorial 



PS 

ft 



restore point size 
restore font 




hD 

,\rti -1i fO 



\" set hD to activate at header trap 
\" set fO to activate at footer trap 




This header prints the date (current each day) and current page number 
at the upper right hand of the page. The footer prints an essay title in ital- 
ics at twelve point, reverts to the previous font and point size and calls for 
the next page to be printed. Because you can define macros to collect and 
print text and register values as well as to perform requests, escape 
sequences, macros, you begin to see how powerful the page trap can be. 
But more on traps later. Instead let's explore testing and conditional state- 
ments further. 



Testing and conditional activity, at this point, are nothing novel in 
nroff/troff . You have seen them in the need request, which specified when 
text would be processed, and in the page trap, which specified both when 
and what text would be processed. The if requests (.if, .ie, .el) add one 
more capability to these: they decide whether text will be processed. 

The two tables below will give a rough overview of the if requests and 
will set out terms from which to work. In the following, c is a one- 
character, built-in condition name, ! signifies not, N is a numerical expres- 
sion, u stands for basic units (a device-dependent measure), stringl and 
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string! are strings delimited by any non-blank, non-numeric character not in 
the strings, and anything represents what is conditionally accepted: 



Request Form 


Explanation 


•if c anything 


If condition c true, accept anything as input; 




in multi-line case use \{anything\] , 


.if !c anything 


If condition c false, accept anything. 


.if N anything 


If expression N > 0, accept anything. 


.if IN anything 


If expression N < 0, accept anything. 


.if 'stringl 'string!' anything 


If stringl identical to string!, 




accept anything. 


•if Vstringl' string!' anything 


If stringl not identical to string!. 




accept anything. 


Ae c anything 


If portion of if-else; all above forms (like .if). 


.el anything 


Else portion of if-else. 


The built-in condition names are: 


Condition 




Name 


True If 


o 


Current page number is odd 


e 


Current page number is even 


t 


Formatter is troff 


n 


Formatter is nroff 



If the condition c is true, then anything (requests, escape sequences, or 
text) is accepted for input. Likewise, if the number N is greater than zero, 
anything following the conditional expression is input. If the strings com- 
pare identically (including motions and character size and font), anything is 
accepted as input. Finally, if a ! precedes the condition, number, or string 
comparison, the sense of the acceptance is reversed. 

Any spaces between the condition and the beginning of anything are 
skipped over. The anything can be either a single input line (text, macro, or 
whatever) or a number of input lines. In the multi-line case, the first line 
must begin with a left delimiter \{ and the last line must end with a right 
delimiter \}. 
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The request .ie (if-else) is identical to .if except that the acceptance state 
is remembered. A subsequent and matching .el (else) request then uses the 
reverse sense of that state, .ie-.el pairs may be nested. 

All this may seem daunting at first, but a few examples will show the .if 
requests to be in fact quite tame. Perhaps the most common use of these 
requests is to distinguish between nroff and troff parameters. Often a 
document is destined to be formatted by each of these programs depending 
on the occasion. Preparing two different versions would be wasteful; the .if 
requests allow you to prepare two sets of parameters for one document. 
Each set automatically activates when its corresponding formatter is used. 

The following abbreviated examples show how this is done: 




.if n \{ \ \" if nroff 

.ft R \" use reman font 

.ps 10 \" use point size ten 



You undoubtedly noticed that n and t correspond to nroff and troff, respec- 
tively. These are permanent, predefined condition names and will never 
change. When using nroff to format your document, the .if request asks 
that parameters suitable for a mechanical printer be used; if troff were used, 
a format appropriate to digital typography would be used. 



etc. \ } 

.if t \{ \ 



\" if troff 
\*' load Palatino font 
\" use Palatino font 
\" use point size nine 



.fp 1 PA 
.ft PA 
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We could have done this in a slightly more straightforward fashion: 



.ie t \{ \ V if tzoff 

.£p 1 PA \" load Falatino at positiGn one 

.ft PA \" use Palatino 

,ps 9 \" use point size 9 
etc. 

.el \{ \ \" or else 

.ft R \" nake zonan your predondnant font 

.p6 10 \" use point size ten 
vetc. \ } 



If troff is used, execute all formatting commands inside the correspond- 
ing delimiters. If not, then do all formatting commands within the second 
set of delimiters. Since the only alternative to troff is nroff, else will 
always mean nroff in such a case. 

Each set of .if requests has its own corresponding pair of delimiters. 
The delimiters are to unify several lines of formatting commands into a sin- 
gle package belonging to its controlling .if request. Had the request .el 
been followed by a single request, the delimiters would not have been 
necessary: 

.el .ft R 

(Notice that in previous examples, subsequent requests or macros on control 
lines do include dots, unlike the .wh request.) 

The preceding example would have been duplicated, in effect, with this 
even shorter solution: 
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.if t \{ \ 
.£p PA 
.ft 1 PA 
.ps 9 
... \ } 



If you were to use nroff, the «if request would be ignored/ and you 
would get default values (which we were assigning to nroff anyway). If 
you used troff, the parameters following .if would apply. 

Notice that in the above examples the opening if-statement delimiter 
(\() is trailed by a final backslash, escaping the newline character. The start- 
ing delimiter expects to be followed by a formatting command or text. By 
escaping the newline, this requirement is met. 

If we had used .if requests in our previous example of page traps for 
headers and footers, it might have looked something like this: 



.de hD 

.ie \\xiK>1 \{\ V For all pages foUowing page cne do the following: 

.ie e .tl ' ' V place page znsdDer at ^sppsc left of even pages 
.el .tl ' ' \" place page nuober at ysppex ri^^t of odd pages 

'sp ! 1i M \" then space down odb inch 

.el 'sp ! 1.25i\ \" Don't umber first page and make larger header 
.«h hD 



Notice the nesting in this example. Inside the main if-else statement 
(which determined activity based on first-page and non-first-page status) 
was another if-else (which determined activity based on even and odd 
pages). This nest of conditional statements was delimited by \{\ and \}. 
Like n and t, e and o are predefined condition names for even and odd 
pages, respectively. These too are permanent definitions. 
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A more realistic example of header and footer control would be the fol- 
lowing: 



.de 


hD 


\" 


header 


.if 


t .tl — — 


\" 


troff cut nark 


.if 


\\n56>1 \{ \ 






'sp 


1 0.5i-1 


\" 


tl base at 0.5i 


.U 


"- % -" 


\" 


centered page number 


.ps 




\" 


restore size 


.ft 




\" 


restore font 


.vs 


\ } 


\" 


restore vs 


- i'f 

sp 


1 I.Oi 


\" 


space to l.Oi 


.ns 




\" 


turn on no-space mode 


.de 


fO 


\" 


footer 


.ps 


10 


\" 


set footer /header size 


.ft 


R 


\" 


set font 


.vs 


12p 


\" 


set base line spacing 


.if 


\{ \ 






'sp 


1 \\n(.pu-0.5i-1 


\" 


tl base 0.5i up 


•tl 


"-%-' \ } 


\" 


first page number 


'bp 








.vdi 


hD 


\" 


set tQp-of-page trap 




-1i fO 


\" 


set botton-of-page trap 



This arrangement sets the size, font, and base line spacing for the 
header/footer material and ultimately restores them. The material in this 
case is a page number at the bottom of the first page and at the top of the 
remaining pages. 

If you are typesetting text on a device that produces a continuous role 
of paper, you must specify a cut mark at the bottom of each page. This was 
done above by simply requesting that hyphens be drawn using the .tl 
request. 

The .sps refer to absolute positions to avoid dependence on the base 
line spacing. Another reason for absolute spacing in the footer is that the 
footer is invoked by printing a line whose vertical spacing swept past the 
trap position by possibly as much as the base line spacing. The no-spacing 
mode is turned on at the end of .hd to render ineffective accidental 
occurrences of .sp at the top of the running text. 
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The above method of restoring size, font, and leading presupposes that 
such requests (that set previous value) are not used in the running text. A 
better scheme is to save and restore both the current and previous values 
for size as the following shows: 



de f O 

nr si \\n( .s \" current size 
ps 

nr s2 \\n( .s \" previous size 

etc. \" rest of footer 

de hD 

\" header stuff 

ps \\n(s2 \" restore previous size 

ps \Nn(s1 \" restore current size 



Page numbers can be printed in the bottom margin by a separate macro 
triggered during the footer's page ejection: 




.tl % -" \*' centered page nmrtoer 



.wh -0.5i-1v bn Vtl base 0.5i up 




While an exhaustive presentation of troff's features and applications is 
not practical in a tutorial, its great flexibility and precision can certainly be 
shown. Some of the unusual — in some cases, unique— capabilities we have 
not discussed are well worth learning through the "nroff/troff Technical 
Discussion" in the Technical Discussion and Reference Manual. 
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With troff you are able to divert text into special save-areas and measure 
its dimensions, placing the text according to your findings while the job is 
running. Once you have placed traps, you can calculate the distance to the 
next trap, defining macros to behave according to that distance. You can 
create your own automatically incrementing registers and set them accord- 
ing to textual dimensions or contextual page behavior. In short, troff pro- 
vides both a nimble text processing facility as well as an elaborate instru- 
ment for determining the weights and measures of words. Finally, these 
complementary features combine in a programming language that can be 
effectively used with other UNIX system tools and languages enabling you 
to undertake applications of considerable variety and scope. 
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Introduction 



This tutorial describes how to use eqn and neqn, tools for presenting 
mathematical notation. These programs are run from the command line as 
preprocessors, preceding their corresponding formatters, troff and nroff . 
With eqn or neqn you specify mathematical expressions with control lines 
that you can set up like a display or embed in the running text of a 
manuscript. This tutorial gives examples of eqn output only. 

The prerequisites to benefit from this tutorial are as follows: 

■ You should know what a file and directory are and how to 
create them. See the UNIX System V User Guide, 

■ You should know how to use a UNIX system text editor (such 
as ed or vi) to create and change files. See the UNIX System V 
User Guide. 

■ You should know how to run programs with options and 
how to use pipes. See the UNIX System V User Guide. 

■ You must have a working knowledge of nroff or troff, prefer- 
ably troff. See the tutorials in this guide "The Formatter 
nroff" and 'The Formatter troff," 

■ Your understanding of eqn/neqn would benefit from 
knowledge of the mm macro package though it is not essen- 
tial. "The Macro Package mm" gets you started, and "The mm 
Macro Package: Technical Discussion" in the Technical Discus- 
sion and Reference Manual explains it in detail. 



Other preprocessors that you may use with eqn/neqn are discussed in 
tutorials in this guide. You may also refer to the "nroff /troff Technical Dis- 
cussion" in the Technical Discussion and Reference Manual. 



eqn and neqn are identical in their input. Their output, though, is 
different, neqn is a preprocessor to nroff, and its output is printed on 
typewriter-like devices such as the DASI 300, 300S, and 450; the C-Itoh 8510; 
the DTC 382; and the Teletype Model 37. eqn is a preprocessor to troff, and 
its output is typeset on digital typesetters such as the Autologic APS 5. The 
results of neqn are a rough draft of eqn's output, because neqn's output 
devices do not provide the variety of characters, sizes, and fonts that a 
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typesetter does, neqn's output devices, themselves, vary in sophistication. 
Some, for instance, do not allow for vertical motions necessary for sub- 
scripts and superscripts and print such notation on the equation's baseline. 

Because the input of eqn and neqn are so similar, this text uses 
"eqn/neqn" to refer to both programs, unless a functional distinction 
requires otherwise. 
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The following sections introduce you to the macros, keywords, meta- 
characters, and font and point size controls needed to use eqn. 



Displayed Equations (.EQ and .EN) 

To tell eqn/neqn where a mathematical expression begins and ends, use 
the macro pair .EQ and .EN. Thus if you have a file containing the lines 

.m 

your output will look like this 

The following command line uses troff to process the output: 

eqn [ options ][file] \ troff [ options ] | phototypesetter 

The following command line preprocesses the equation for the nroff for- 
matter: 

neqn [ options ] [ file ] | nroff [ options ] | printer 

Your system administrator should know what printer name is appropriate 
for your output. 

The delimiters .EQ and .EN are copied untouched; they are not other- 
wise processed by eqn/neqn. You must take care of things such as position- 
ing equations on the page yourself. The most common way to handle this 
is to use the mm display macros, which allow you to center or indent text 
blocks. This tutorial gives tips for using .EQ and ,EN with the display del- 
imiters in the section entitled "Troubleshooting." 

Any equation can be labeled with an arbitrary equation number, which 
appears at the right margin when your file is printed. For example, the 
input 

.BQ I (2a) 

X = f (y/2) + y/2 

produces the output 
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x^fiylD+yll (2a) 



Shorthand for In-line Equations (delim) 

In a document containing mathematical notation, you should follow 
mathematical conventions not just in display equations, but also in the body 
of the text. For example, variable names such as x should be in italic. 
Although you could do this by surrounding the appropriate input with .EQ 
and .EN, it would be a nuisance to continually repeat these delimiters. 

eqn/neqn provides a shorthand method for presenting short in-line 
expressions. You can define two characters to mark the beginning and end 
of in-line expressions, and then use them to type expressions right in the 
middle of text lines. To set both the left and right characters to pound 
signs, for example, add the following three lines to the beginning of your 
document: 

delim ## 
.EN 

Having set these delimiters, you may use them in your text to indicate 
mathematical expressions that need to be processed by eqn/neqn. For 
example: 

Let #alpha sub i# be the primary variable, and let ^ta# be zero. 
TSien we can show that #ic sub 1# is #>=0#, 

Spaces, new-lines, and so on, are significant in the text, but not inside 
the eqn/neqn expression itself. More than one expression can occur in a 
single input line. 

Let a, be the primary variable, and let jS be zero. Then we can 
show that Xi is >0. 



4 USER'S GUIDE 



Typesetting Equations with eqn 



Adequate room should be made before and after a line containing an 

n 

in-line expression so that something such as ^jc, does not interfere with 

1-1 

the lines surrounding it. Once pound signs, for example, have been made 
eqn delimiters, all instances of them will have a special meaning. 

To turn off the delimiters type the following lines: 

,BQ 

delim off 
.EN 

Don't use braces, tildes, circumflexes, or double quotes as delimiters, or 
you will get unwanted results. Also, you must close in-line font changes 
(for example, \f3) before you begin in-line equations. 



Spaces and Newlines within .EQ and .EN 

Spaces and new-lines within an expression are thrown away by 
eqn/neqn. Thus between •EQ and .EN, or between whatever characters you 
have defined as expression delimiters, 

x=y+z 

and 

X = y + 2 

and 

X = y 

+ z 

all produce the same output: 
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Output Spaces 

To force spaces to appear in the output, use a tilde for each space 
you want: 

x-=-y-+-z 



X « y + z 

You also can use a circumflex C), which gives a space that is half the width 
of a tilde. It is useful for fine-tuning. Tabs also may be used to position 
pieces of an expression, but the tab stops must be set by nroff or troff . 

Symbols, Special Names, and Greek 

eqn/neqn knows some mathematical symbols, some mathematical 
names, and the upper- and lower-case ancient Greek alphabet. For example 

•EQ 

x=2 pi int sin ( omega t)dt 
produces 



Here the spaces in the input are necessary so that eqn/neqn can recognize 
int, pi, sin and omega as keywords that get special treatment. On output, 
the sin, the digit 2, and the parentheses are each set in roman type instead 
of italic; pi and omega become their Greek counterparts; and int becomes 
the integral sign. 

When in doubt, leave spaces around separate parts of the input. A com- 
mon error is to type £(pi), for example, without leaving spaces on both sides 
of the pi. As a result, eqn/neqn does not recognize pi as a keyword, and it 
appears as / (pi) instead of /(tt). 



gives 
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You must tell eqn/neqn to look in the file /usr/pub/eqnchar for partic- 
ular names and symbols that it would not understand otherwise. To tell it 
to look there, use the following command line, 

eqn/neqn /usr/pub/eqnchar [ ^/^ ] | troff 

Here is a complete list of the kejnvords and their corresponding symbols 
that are in /usr/pub/eqnchar: 



ciplus 


e 


II 


II 


square 


□ 


citimes 




tangle 


( 


circle 


O 


wig 




rangle 


> 


blot 


■ 


-wig 


iwig 


hbar 


H 


bullet 


• 


>wig 


> 


ppd 


JL 


prop 


oe 


<wig 


< 


<-> 




empty 





^wig 




<-> 


CO 


member 


€ 


star 




l< 


< 


nomem 




bigstar 




l> 


> 


cup 


u 


-dot 




ang 


z 


cap 


n 


orsign 


V 


rang 


L 


incl 


c 


andsign 


A 


3dot 




subset 


c 


-del 


A 


thf 




supset 


D 


oppA 


V 


quarter 


Vi 


Isubset 


Q 


oppE 


B 


^quarter 


Va 


Isupset 




angstrom 


A 


degree 


o 


scrL 


e 




< 


--> 


> 







Spaces, Again 

The only way that eqn/neqn can deduce that some sequence of letters 
might be special is if that sequence is separated from the letters on either 
side of it. You can do this by surrounding a keyword by ordinary spaces (or 
tabs or new-lines), as explained in the previous section. 

You can also make special words stand out by surrounding them with 
tildes or circumflexes: 
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x-s3-2-pi-int-sin- ( -oraega-t- ) -dt 

This is much the same as the last example except that the tildes not only 
separate the special words like sin, omega, and so on, but they also result in 
real spaces in the output, one space per tilde: 



You also can separate special words with braces { } and double quotes 
which have special meanings, as you will see. 

Subscripts and Superscripts (sub and sup) 

Subscripts and superscripts are obtained with the words sub and sup. 

X sup 2 * y sub k 

gives 



eqn/neqn takes care of all the size changes and vertical motions needed to 
make the output look right. Like all special words, sub and sup must be 
surrounded by spaces; x sub2 will give you xsubl instead of X2. Further- 
more, a space (or a tilde) must mark the end of text to be subscripted or 
superscripted. A common error is to say something like 

y = (x sup 2)+1 
which causes 





instead of the intended 



Subscripted subscripts and superscripted superscripts also work: 
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X sub 1 sub 1 
produces 

The same element of an expression can have both a subscript and a super- 
script if the subscript comes first: 

X sub i sup 2 
becomes 

Other than in this special case, sub and sup group to the right, so 
X sisp y sub z 

means 

$x sup {y sub z }$ 

not 

${x sup y } sub z$ 

Braces for Grouping 

Normally, the end of a subscript or superscript is marked simply by a 
blank (or tab or tilde). But what if the subscript or superscript is composed 
of elements that have to be typed in with blanks? In that case, you can use 
braces ({ and )) to mark the beginning and end of the subscript or super- 
script: 

e sap (i Onega t} 

becomes 

Braces can always be used to force eqn/neqn to treat something as a unit or 
just to clarify your intention. Thus: 



THE PREPROCESSOR eqn 9 



Typesetting Equations with eqn 



X sub {i sub 1} sap 2 

becomes 

with braces, but 

X sub i sub 1 sap 2 

becomes 

which is clearly different. 

Braces can occur within braces if necessary: 
e sup {i pi sup {rho +l}} 

is 

The general rule is that anywhere you can use a single expression such as x, 
you can use multiple expressions if they are enclosed in braces, eqn/neqn 
looks after all the details of positioning and spacing. 

Always make sure you have the right number of braces. Leaving one 
out or adding an extra causes eqn/neqn to complain. 

Occasionally you have to print braces. To do this, enclose them in dou- 
ble quotes as follows: will give you a literal brace. 

Fractions (over) 

To produce a fraction, use the word over: 
a+b over 2c = 1 

gives 

2c 
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The line is automatically made the right length and positioned. Braces 
can be used to clarify what goes over what: 

{alpha -I- beta} over {sin (x)> 

becomes 

sin(x) 

What happens when there is both an over and a sup in the same expres- 
sion? In such an ambiguous case, eqn/neqn interprets the sup before the 
over, so 

-b &jp 2 over pi 
becomes 

TT 

instead of 

The rules that decide what operation is done first in cases like this are 
summarized below in the section, "Keywords and Precedences." When in 
doubt, however, braces will make clear what goes with what. 

Square Roots (sqrt) 

To draw a square root, use sqrt: 

sqrt a-hb + 1 over sqrt {ax sup 2 +bx+c} 

is 

y/aTb+ . ^ = 

Square roots of tall quantities do not look attractive, because a root-sign big 
enough to cover the quantity is too dark and heavy: 

sqrt { a sup 2 over b sub 2 ) 

is 



THE PREPROCESSOR eqn 1 1 



Typesetting Equations with eqn 



Big square roots are generally better written in an alternative style of 
mathematical notation: 

(a sup 2 A> sub 2 ) sop half 
which becomes 

Summation and Integral (sum, from, and to) 

Summations, integrals, and similar constructions are easy: 
sum from i=0 to {i- inf} x sup i 
produces 

1-0 

Notice that the braces specify where the upper part, /=<», begins and ends. 
No braces were necessary for the lower part, /=0, because it contained no 
blanks. If the from and to parts contain any blanks, you must use braces 
around them. 

The from and to parts are both optional, but if both are used, from 
must always precede to. 

Other useful characters can replace the sum in our example: 

int prod union inter 

become 

J n u n 

Since the expression before the from can be anything, even something in 
braces, from and to can often be used in unexpected ways: 
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lim frcm {n ~> inf } x sub n =0 

becomes 

limjc„=0 



Diacritical Maries (dot, dotdot, hat, tilde, vec, dyad, 
bar, and under) 

There are several keywords that will produce diacritical marks: 



X dot 


X 


X dotdot 


X 


X hat 


X 


X tilde 


X 


X vec 


X 


X dyad 




X bar 


X 


X under 


X 



The diacritical mark is placed at the correct height and centered over the 
letter. The bar and under marks are made the right length for the entire 
construct, as in jr+y+z . 

Quoted Text 

Any input enclosed in quotes ("...") is not subject to any of the font 
changes and spacing adjustments normally done by eqn/neqn; therefore, 
you can adjust your own spacing if needed: 

italic "sin(x)" + sin (x) 

becomes 

sinix) +sm{x) 

Quotes are also used to get braces and other eqn/neqn keywords 
printed: 
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"{ size alpha }" 
becomes 

( size alpha ] 

and 

ronan "{ size alpha }" 

becomes 

( size alpha ) 

The quote construction, is often used as a place-holder when 
eqn/neqn needs something to fulfill a syntactic requirement, but you don't 
actually want anything in your output. For example, to make S"*" sup 2 
roman Be$, you can't just type sup 2 reman Be because a sup has to be pre- 
ceded by something it can be a superscript of. Thus you must say 
" " sup 2 roian Be 



To print an actual quotation mark use troff characters like \(bs can 
appear unquoted, but something more complicated, like horizontal and vert- 
ical motions with \h and \v, should always be quoted. 



NOIB 



To learn more about \h and \v, see the "nroff/trotf Technical Discussion" 
the Technical Discussion and Reference Manual, 



Lining up Equations (mark and lineup) 

Sometimes it's necessary to line up a series of equations at some hor- 
izontal position, often at an equal sign. You can do this with mark and 
lineup. 

The word mark may appear only once, at any place, in an equation. It 
remembers the horizontal position where it appeared. Successive equations 
can contain one occurrence of the word lineup. The place where lineup 
appears is made to line up with the place marked by the previous mark if 
possible. Thus, for example, you can say 
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to produce 

x+y-2 
x-1 



Brackets, Braces, Parentheses, Bars, and 
Floor/Ceiling 

To get big brackets [], braces [}, parentheses (), and bars || around 
expressions, use the left and right keyivords: 

left { a over b -i- 1 ri^t } 
-=- left ( c over d ric^ ) 
+ left [ e right ] 

becomes 




The resulting brackets are made big enough to cover whatever they enclose. 
Other characters can be used besides these, but they are not likely to look 
good. Two exceptions are the floor and ceiling characters: 

left floor X over y rig^ floor 

<= left ceiling a over b rig^ ceiling 

produces 
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The right construction may be omitted: a "left something" need not 
have a corresponding "right something." If the right part is omitted, put 
braces around the thing you want the left bracket to encompass. Otherwise, 
the resulting brackets may be too large. 

If you want to omit the left part, things are more complicated because 
technically you can't have a right without a corresponding left. Instead you 
have to say 

left"" right) 

for example. The left "" means a "left nothing." This satisfies the rules 
without hurting your output. 

Several warnings about brackets are in order. First, braces are typically 
bigger than brackets and parentheses, because they are made up of three, 
five, seven, or more pieces, while brackets can be made up of two, three, or 
more. Second, big left and right parentheses often are not attractive in 
print. 



Pile (above, pile, Ipile, rpile, and cpile) 

pile is a general facility for making vertical piles of things. For exam- 



ple: 



A left [ 
pile ( a above b above c } 
pile { X above y above z } 
ric^ ] 



makes 



A - 



a X 
f> V 

C 2 



The elements of the pile (there can be as many as you want) are centered 
one above another, at the correct height for most purposes. The keyword 
above is used to separate the elements of the pile; braces are used to delimit 
the list. The elements of a pile can be as complicated as needed, even con- 
taining more piles. 
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There are three other forms of pile: Ipile makes a pile in which the ele- 
ments are left-justified; rpiie makes a right-justified pile; and cpilc makes a 
centered pile, just like pile. The vertical spacing between the pieces is 
somewhat larger for 1-, r- and cpiles than it is for ordinary piles. 

roman sign (x)"«* 
left { 

Ipile (l above above -l) 
{if"x>0 above if*x=0 above if'x<0) 



makes 



sign(x) - 



1 ifjc>0 
ifx-0 
-1 ifx<0 



Notice that the brace is not part of pile's output, but appears because the 
keyword left construction was also used in this expression. This example 
also shows the use of a left brace without a matching right one. 



Matrices (Icol, rcol, ccol, and matrix) 

It is also possible to make matrices. For example, you can use the key- 
words matrix and ccol like this 

natrix { 

cool { X sub i above y sub 1 } 
ccol ( X sup 2 abcFve y sup 2 } 

} 

to array these elements neatly like this 



This produces a matrix with two centered columns. The elements of the 
columns are listed, inside braces, just as for a pile, each element separated 
by the word above. You can also use led or reel to produce left or right 
adjusted columns. Each column can be separately adjusted, and there can be 
as many columns as you like. 
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The advantage of using a matrix instead of two adjacent piles is that 
piles may not line up properly if all the elements don't have the same 
height. A matrix forces elements to line up because it looks at the entire 
structure before deciding on spacing. 

A word of warning about matrices: each column must have the same 
number of elements in it. 



Definitions (define, ndefine, and tdefine) 

eqn/neqn provides a facility for naming a frequently-used string of 
characters, so thereafter you can just type the name instead of the whole 
string. For example, if the sequence 

X sub i sub ^ + y sub i sub 1 

appears repeatedly throughout a paper, you can avoid re-typing it each time 
by defining it like this: 

define xy 'x sub i sub ^ -¥ y sub i sub V 

xy can now be used to stand for whatever characters occur between the sin- 
gle quotes in the definition. You can use any character instead of quotes to 
mark the beginning and end of the definition, so long as it doesn't appear 
inside the definition. 

Now you can use xy like this: 

f (x) = xy , , , 

and so on. Each occurrence of xy expands into its definition. Be careful to 
leave spaces or their equivalent around the name when you use it, so 
eqn/neqn will be able to identify the defined name as a special word. 

There are several things to watch out for. First, although definitions 
can use previous definitions, as in 
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define xi ' x sub i 
define xil ' xi sub 1 
.EM 

don't define something in terms of itself. A common error is to type 
define X ' roion X 

This is a guaranteed disaster since X is now defined in terms of X. If you 
type 

define X ' raian "X" 

however, the quotes prevent the second X from being read as a keyword, 
and everything works fine. 

eqn/neqn keywords can be redefined. You can make / mean over by 
saying 

def ijie / ' over 

or redefine over as / with 
define over ' / 

If you need to print ah element differently on a terminal screen than it 
is printed on a typesetter you can define the same symbol specifically for 
neqn and specifically for eqn. This is done with ndefine and tdefine. A 
definition made with ndefine only takes effect if you are running neqn; one 
made with tdefine only applies for eqn Names defined with plain define 
apply to both eqn and neqn 

Size and Font Changes (size, font, roman, italic, 
bold, and fat) 

By default, equations typeset with eqn/neqn are put in 10-point type, 
and use standard mathematical conventions to determine which characters 
are in roman and which in italic, heqn constrains equations to your 
printer's capabilities. So if you are ohly going to use neqn, you can skim 
the information about size changes. 
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Although eqn/neqn makes a valiant attempt to use aesthetically pleas- 
ing sizes and fonts, it is not perfect. To change sizes and fonts, use size n 
and reman, italic, bold and fat. Like sub and sup, size and font changes 
affect only the element that follows them, and the expression reverts to the 
normal case when it reads a blank space. Thus 

bold X y 

becomes 
xy 

and 

size 14 bold x. - y 

size 14 {alphA + beta} 

gives 

As always, you can use braces if you want to affect something more compli- 
cated than a single letter. For example, you can change the size of an entire 
equation to 12 point by 

size 12 { ... } 

Legal sizes that may follow size are 6, 7, 8, 9, 10, 11, 12, 14, 16, 18, 20, 
22, 24, 28, 36. You can also change the size by a given amount; for exam- 
ple, you can say size +2 to make the size two points bigger, or size -3 to 
make it three points smaller. The advantage of this method is that you 
don't have to know what the current size is. 

If you are using fonts other tfian roman, italic, and bold, you can say 
font X where X is a one character troff name or number for the font. Since 
eqn/neqn expects roman, italic, and bold, other fonts may not give as good 
an appearance. 

The fat operation widens a font by overstriking: fat grad is V and fat 
{x sub 1} is Xj. 

If an entire document is to be in a non-standard size or font, it would 
be a severe nuisance to have to write out a size and font change for each 
equation. Accordingly, you can set a global size or font to thereafter affect 
all equations. At the beginning of any equation, you might say, for 
instance. 
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gsize 16 
gf ont R 

to set the size to 16 and the font to roman thereafter. In place of you can 
use any of the troff font names. The size after gsize can be a relative 
change with + or — . 

Generally, gsize and gf ont appear at the beginning of a document, but 
they can also appear throughout a document: the global font and size can be 
changed as often as needed. For example, in a footnote in which the rela- 
tive point size and leading is smaller than in general text, the size of equa- 
tions should match the size of the footnote text. Don't forget to reset the 
global size at the end of the footnote. 



Local Motion (back, fwd, up, and down) 

Although eqn/neqn tries to get most things at the right place on the 
paper, it isn't perfect, and occasionally you need to fine-tune the output to 
make it just right. Small, extra horizontal spaces can be obtained with tilde 
and circumflex. You can say back n and fwd n to move small amounts hor- 
izontally, n is how far to move in 1/100's of an em (an em is about the 
width of the letter m). Thus back 50 moves back about half the width of an 
m. Similarly you can move things up or down with up n and down n. As 
with sub or sup, a local motion affects only the next element in the input, 
which can be several elements enclosed in braces. 
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Keywords and Precedences 

If you don't use braces, eqn/neqn does operations in the order shown 
in each line in this list. 

dyad vec under bar tilde hat dot dotdot 

fwd back down up 

fat reman italic bold size 

sub sup sqrt over 

from to 

These operations group to the left: 

over sqrt left right 

All others group to the right. 

Digits, parentheses, brackets, punctuation marks, and these mathemati- 
cal words are converted to roman font when encountered: 

sin cos tan sinh cosh tanh arc 
max min lim log In exp 
Re Im and if for det 

The following list shows special character sequences in their input form 
(left column) and output form (right column). 



>= 


> 


<= 












+- 


± 


-> 




<- 




<< 


« 


>> 


» 


inf 


oo 


partial 


d 


half 




prime 




approx 




nothing 




cdot 
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times X 
del V 
grad V 



sum 2 

int / 

prod n 

union (J 

inter H 



To obtain Greek letters, simply spell them out in whatever case you 
want: 



DELTA 


A 


iota 


I 


GAMMA 


r 


kappa 


K 


LAMBDA 


A 


lambda 


X 


OMEGA 


n 


mu 


M 


PHI 


$ 


nu 


V 


PI 


n 


omega 


0) 


PSI 




omicron 





SIGMA 


s 


phi 


4> 


THETA 


e 


pi 


IT 


UPSILON Y 


psi 




XI 


A 


rho 


P 


alpha 


a 


Sigma 


a 


beta 


/J 


tau 


T 


chi 


X 


theta 





delta 


5 


upsilon 


V 


epsiion 


c 


xi 




eta 


r) 


zeta 


r 


gamma 


y 
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These are all the words known to eqn/neqn except for the following 
characters with names: 





P 


back 


marlc 


L/ai. 




bold 


ndefine 


ceiling 


wci 


CCf%\ 


pile 




rcul 


cpile 




define 


roman 


delim 


rpile 


dot 


size 


dotdot 




down 


fiiih 

9Ut/ 


dyad 




fat 




floor 


tilde 


font 


to 


from 


under 


fwd 


up 


gfont 


vec 


gsize 


A 

/ 


hat 


{) 


italic 


It n 


Icol 




left 




lineup 




Ipile 
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Troubleshooting 



If you make a mistake in an equation, such as leaving out a brace (a 
common mistake) or typing one too many, or typing sup with nothing 
before it, eqn/neqn gives you an error message of the following form: 

ecpi: syntax error 

file file, between lijies n and w+x 

where n and n+x are approximately the lines between which the trouble 
occurred; and file is the name of the file in question. There are also self- 
explanatory messages that arise in other circumstances. 

If you want to check the document file before printing it (on the UNIX 
system only) type the following: 

eqn file >/dev/null 

This command line throws away the output but prints any error messages. 

If you use something like dollar signs as delimiters, it is easy to forget 
one, which causes trouble. The program checkmm checks for misplaced or 
missing dollar signs and similar troubles. 

The size of in-line expressions is limited because of an internal buffer in 
the formatter troff . If you get a message "word overflow," it means you 
have exceeded this limit. If you print the equation as a displayed equation, 
this message usually goes away. The message "line overflow" signifies that 
you have exceeded an even bigger buffer. The only cure for this is to break 
the equation into two separate ones. 

On a related topic, eqn/neqn does not break equations by itself; you 
must split long equations across multiple lines by yourself, marking each by 
a separate .EQ and .EN sequence, eqn/neqn does warn about equations that 
are too long to fit on one line. 

When you format equations in an mm document, you must surround 
the delimiters •EQ and .EN with the mm display macros .DS and .DE. 
There is an exception to this rule; if you use .EQ and .EN only to specify 
the delimiters for in-line expressions or to specify eqn/neqn "defines" 
(which are explained above), do not use .DS and .DE. To do so causes extra 
blank lines to appear in the output. However, when you use .EQ and .EN 
to specify delimiters for in-line equations, one line of text before .EQ gets 
lost unless you take precautions. For example, suppose the document looks 
like this: 
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Troubleshooting 




.p 

ISiis is a line of tesct. 
.BQ 

delim $$ 




"This is a line of text" gets lost because it is not flushed from the line buffer 
before the .EQ is encountered. One remedy is to insert the nroff/troff 
break instruction before .EQ: 




.p 

This is a line of text. 

.hr 

.EQ 



delim 
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Introduction 



This tutorial is intended to give you a working knowledge of pic, the 
DOCUMENTER'S WORKBENCH Software tool for drawing pictures. It will 
also introduce you to pic's programmable features. With this knowledge 
you will be able to draw figures and characters to be used in text. You will 
also learn how to implement advanced features, such as loops and condi- 
tional statements, for handling drawing tasks in sophisticated ways. What- 
ever uses you have for pic, your pictures will be fully integrated in the text 
formatting world of troff and will be treated as part of the text in large or 
small printing jobs. 

For a brief technical discussion of the pic language, see the Technical 
Discussion" near the back of this tutorial. For a variety of pic examples, see 
the "pic Sampler** immediately following the *Technical Discussion." 

You should be familiar with the following concepts and tools to fully 
benefit from this tutorial. 

■ You should know how to use a UNIX System V text editor 
(ed, vi, and ex are examples). See the UNIX System V User 
Guide. 

■ You should know what a file and directory are and know 
how to manipulate them. See the UNIX System V User Guide, 

■ You should know how to redirect input and output using 
pipes. See the UNIX System V User Guide. 

■ You should be familiar with a UNIX System V formatter 
(nroff or troff). See the tutorials in this book that discuss 
nroff or troff. 

■ Your understanding of pic would be assisted by a knowledge 
of grap though this is not essential. To learn about grap, see 
*'The Preprocessor grap" in this book. 
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Basics 



pic is a simple language for drawing pictures. Since it produces 
typesetter-quality text, it is used in conjunction with troff . You introduce 
pictures into your document by using macros (.PS and .PE) and by insert- 
ing, between those macros, instructions that pic understands. The format 
looks like this: 

.PS 

box "this is" "a box" 
.FE 

And the result looks like this: 



this is 
a box 



You would process the file that contains this bit of pic with the following 
command line: 

pic file I troff | typesetter 

You need to use troff here rather than nroff because pic requires the free 
motions of digital typography to make its pictures: you, naturally, could not 
use a daisy-wheel printer to produce pic's variegated forms. 

The .PS and .PE macros (pic start and pic end) mark off and define pic's 
workspace. In the area set off by these macros you use pic's special instruc- 
tions rather than nroff or troff requests and macros. This does not mean 
that pic is not an integral part of the document. On the contrary it is fully 
part of the troff environment in which you are developing your text. (In 
fact, pic makes its pictures, or forms, by automatically writing requests and 
escape sequences that are given to troff to interpret as it interprets the rest 
of your requests, escape sequences, and macros.) What it does mean is that 
pic has its own particular language, which is more English-oriented than 
are most formatting commands. 

pic offers a basic set of forms that you make by simply naming them. 
The following illustration shows them in their default sizes: 
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line 



arrow 



box 




arc 



These pictures were made by naming them inside the area marked off by 
.PS and .PE. (Naturally, saying "box" or "ellipse" anywhere else in troff 
would produce merely the letters you typed and not the forms these words 
are able to materialize in pic.) 

The following examples of input produced the forms given above: 



line "line" above; mcfve 

arrcw "arrcw" above; move 

box "bojc"; move 

.PE 

.Sp 1 

.PS 

circle "circle"; move 
ellipse "ellipse"; move 
arc "arc"; move 

J 

This input example is divided into two pic groups; in between each group 
of two is the troff request, .sp. The point here is that, while pic generates 
requests and escape sequences for troff to read, it does not itself understand 
troff code. You must speak to pic in its native tongue; it will do the 
translating for troff. Thus, if you want to intersperse troff requests or 
escape sequences, you must first get out of the pic workspace for a moment 
with .PE. 
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Notice also in order to place text inside forms, you must follow the 
form's name with the words you want, setting them off with double quotes. 
Each line of words must have its own set of quotes. If, for example, you 
wanted to place two lines of words in a box like this: 



This is not 
a circle. 



you would use the following input file: 

.PS 

booc "Hiis is not" "a circle." 
.FE 

Each set of quoted words occupies a separate line because each has its own 
set of quotes. Don't be fooled by these quoted words; they bear no respon- 
sibility for making a given form: 




Many of the examples above introduce ordinary English words or text 
into their pictures, pic not only permits you to integrate these, but also 
allows you to adjust where they appear. While there may be times you 
would like the option of putting an arrow through something: 

Arrow — ^ 

it will not often be your choice. Normally, you'll want to place words 
where you can read them clearly. To place a word above a line you would 
follow the word with above; a word to be placed below would be followed 
with below. The shot-through "Arrow" shown above was made with this 
input: 



4 USER'S GUIDE 



Basics 



.PS 

arrow right 1.25i "\s14\f2ftrrow\f 1\sO" 
.PE 

The arrow itself points to the right and is one and a quarter inches long. 
The word "Arrow" is specified to be in italic and given in fourteen points. 

.PS 

lijie "Word" above: 
line "Ward" belcw: nove 
line "above" "below" 
.PE 

would give you 

Word above 

Word below 

The third case, as you probably noticed, was not followed by either 
above or below. Rather it was the order in which the text was given that 
determined its placement. 

These methods are easy and useful. But they are not the most precise 
methods pic has to offer. In succeeding pages you will learn to navigate 
your way around pic's forms using even compass points to place text. 

Note how the input examples you have seen throughout are separated 
from one another. Each shape has its own set of instructions. Each stands 
alone on its own line or is followed by semi-colons, a substitute for a new 
line. Even move must be set off by semi-colons. 

move is not a shape but might be understood as one of pic's invisible 
forms. Consider these two closely related examples. The first uses arrows, 
which separate boxes: 

.PS 

box "iiiput"; arrow 

box "\f3pic\f1 ana" "\f3trof£\f 1"; arrow 

box "output" 

.PE 

The second example uses space to separate boxes with the move instruction: 
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.PS 

box "1"; nowe 
box "2"; move 
box "3"; nove 
.FE 

Notice that both the arrow and the move instructions are set off by semi- 
colons: they each have their separate pic function and need to be segregated 
from the box function. 

The output of these two pic diagrams demonstrates that move, though 
invisible, has the same status as arrow or any other form: 



input 




pic and 
troff 


^ 


output 


> 
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Direction of iUlotion 



Most pics appear in a left-to-right fashion, but you can choose other 
directions. The pic instructions to move downward look like this: 

.PS 

dcMn; box; azrcw; ellipse; arrcw; circle 
.FE 

The result follows: 




Once you specify a direction, the whole sequence of forms moves in that 
direction until you tell pic otherwise. The following input file includes a 
succession of different movements: 
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dCMn; Ixsc; arrcw; ellipse; arrow; circle 

right; arrow; box; arrow; ellipse; arrow; circle 

anew; box; ainxw; ellipse; arrcw; circle 
left; arrow; bcx; arrow; ellipse; anew; box invis "Stop!" 

J 

which would produce this: 




You can also specify "mini-environments" for direction of movement. If 
instructions are enclosed in braces, the established direction of motion 
inside the braces is isolated from the pic instructions outside. When the 
enclosed instructions are finished, all motion will revert to values esta- 
blished before the braces. Nothing else is restored. 
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Control of Size and Distance 



The forms you have seen to this point each have been given in reason- 
able dimensions, pic tries to choose sensible measures, so that simple 
figures can be drawn without much bother. That is, if you don't mention 
what size you would like a particular shape to be, you will get default sizes. 
The following dimensions are understood to be in inches, pic's exclusive 
measure: 

arcrad = 0.25 circlerad=0.25 

arrowwid = 0,05 arrowht = 0.1 (arrowhead dimensions) 

boxwid = 0.75 boxht « 0.5 

ellipsewid = 0.75 ellipseht = 0.5 

linewid = 0.5 lineht = 0.5 

movewid = 0.5 moveht = 0.5 

textwid =« textht = 

dashwid = 0.05 scale = 1 

These are known as "variables," and provide information to their 
corresponding forms. The abbreviations given here are standard pic terms: 
wid or width; rad or radius; ht or height. The abbreviation and the term it 
stands for may be used interchangeably in the pic language. 

But you may want to view these dimensions as just a starting place. 
Each form will accept arguments to tailor its precise shape to suit your 
needs. For example, the input 

.PS 

box width 3 height 0.1 
.PE 

draws a long, flat box 

C I 

3 inches wide and 1/10 inch high. If you forget to include the i (indicating 
inches), pic will infer what you mean since it uses no other measure. (If 
you prefer to state the i, however, no space may intervene between it and 
its corresponding number.) 

Changing one box does not change them all. The next box you ask for 
after this flat one will look like the ones you saw earlier. You can change 
the default sizes for pic's forms, but that will be discussed later. 
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The attributes of height (which you can abbreviate to ht) and width (or 
wid) apply to boxes, circles, ellipses, and to the head on an arrow. The 
attributes of radius (or rad) and diameter (or diam) can be used for circles 
and arcs if they seem more natural. 

The easiest way to draw lines and arrows is to state their direction and 
distance relative to wherever you are. The words up, down, left and right 
are all the terms you need to get started. You simply attach them to the 
form you want (line, arrow, or move) and pic will produce the result its 
language suggests. For example, 

.PS 

line xxp 1i ri^ 2i; axzcw left 2i 

move left O.li; lane <-> down 1i "hei^it" 

.FE 



The notation <— > indicates a two-headed arrow; use — > for a head on the 
right end and <— for one on the left. Lines and arrows are, technically 
speaking, the same thing; in fact, arrow is a synonym for the expression, 
line — >. 

If you don't put any distance after up, down, and so on, pic uses the 
standard distance. So 



draws 



hei ;ht 




.PS 

line \sp ri^; line dCMi; line dcwn left; line up 
,PE 



draws the parallelogram 
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Control of Size and Distance 



Should you want to change whole classes of forms, you can do this by 
resetting the default measures assigned to the variables given above. For 
example, you could set ellipsewid to two inches if you find the standard 
half inch ellipse too small: 

.PS 

ellipsewid » 2 

ellipse 

.PE 

would produce 



C. 



You should realize, however, that by setting ellipsewid to two inches, you 
have also set all succeeding ellipses in your document to two inches. 
Unlike the notation, 

ellipse width 3 

which would affect only the ellipse following it, the variable ellipsewid 
provides the width information for every ellipse in the document. 

Let's make more pictures without mentioning the variable, ellipsewid. 
First, the input: 




Now, the output: 
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All ellipses are two inches wide while circles are unaffected. It is prudent, 
therefore, to reset variables as you get ready to leave the pic workspace: 

.PS 

ellipsewid = 3 
ellipse 

ellipsewid » 0.75 
.PE 
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Texture 



As you probably gathered from the User's Guide's Sampler, boxes and 
lines may be dotted or dashed; 



were made from 

.PS 

boK dotted; line dotted; move; line dashed 
.FE 

What you may not know is that the length of these dashes and distance 
between dots is also subject to your control. If there is a number after dot, 
the dots will be that far apart. You can also control the size of the dashes 
(at least somewhat): if there is a length after the word dashed, the dashes 
will be that long, and the intervening spaces will be as close as possible to 
that size. So, for instance. 



comes from the following inputs: 
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line rig^ 4.5i clashed 

.FE 

.PS 



lijie ric^ 4.5i dashed 0.25i 

.FB 

.PS 

line ri^ 4.51 dashed 0.5i 

.FE 

.PS 

line right 4.5i dashed 1i 

J 

Circles and arcs cannot be dotted or dashed. 
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Positioning Text 



An interesting texture— it might be called a non-texture — is invisible or 
simply invis. You produce this by adding the word invis after the pic 
form. This is also a particularly easy and natural way to position things in a 
general format: 

input ^ output 



This neatly balanced figure was done with 

.PS 

bcx invis "input"; arrow; box invis "output" 
.FB 

pic also permits you to specify text alone without an accompanying 
invisible form. You must, however, retain the double quotes to distinguish 
text from other pic instructions. For example, you could have given 

.PS 

"input"; arrow; "output" 
.EE 

and your result would have approximated the example that used invis: 

in put ou t p ut 

As you can see, this picture suffers from a problem of placement. You need 
to move the text to make it readable: 

.PS 

"input"; move; arrow; move; "output" 
.PE 

and you would get this improved result: 

input >■ output 

The issue of placement gets at the heart of invis's usefulness for positioning 
text. Because you can name a form and not print it, you can take advantage 
of the form's virtues discussed in the section, "Mapping and Naming pic's 
Forms." That is, you can specify a corner or other relative position with 
respect to the invisible form. The following example will not use the invis 
instruction, so you can see the demonstration more clearly: 
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.PS 

A: bcac 

"This is northeast" at A.ne ljust 
.PE 

The second line of these instructions uses a colon to associate the letter A 
with a box. The box is then referred to as A on the next line with the suffix 
ne (separated by a dot). This compass point tells pic to place the quoted 
string to the northeast of the named box: at A.ne: 



The instruction ljust is added to ensure that the word will be left adjusted 
with respect to box A. But this is a taste of things that are yet to come. 

pic also knows arithmetic, and you can give it expressions that you 
would like to appear in a form. The instruction you would use is plot: 

.PS 

ellipsewid = 2 

ellipse "TSie ejqpressian 167 nod 44"; arrow "equals" above; move; plot 167 % 44 

ellipsevdd = 0.75 

.FE 

Here is the result: 



iThis is northeast 




16 
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Changing Default Sizes 



The "width" of an arrowhead is the distance between the widest part of 
the vee. The "height" is the distance along the shaft from back of the 
arrowhead to the tip. 

By default, arcs move in a ninety-degree motion counterclockwise from 
where you are right now, and arc cw changes this to clockwise. The default 
radius is the same as for circles, but you can change it with the rad attri- 
bute. It is also easy to draw arcs between specific places; this will be 
described in the next section. 

To put an arrowhead on an arc, use <— , — > or <— > 

In each picture, unless an explicit dimension for some object is specified, 
you will get the default size. You can store non-default sizes in the pic 
reserved word, same. Thus, if you chose a box to be wide and shallow and 
wanted succeeding boxes to do the same, you would follow the word box 
with the extra information same. In the set of boxes given by 

.PS 

dcMn; bGK ht 0.2i wid 1.5i; move down 0.151 
box same; move same; box sane 



the dimensions set by the first box are used several times; similarly, the 
amount of motion for the second move is the same as for the first one. 

It is possible to change the default sizes of objects by assigning values to 
certain pic variables. So if you want all your boxes to be long and skinny 
and relatively close together, for example, use the following input. 
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.PS 

boxwid = O.li; boodit = 1i 

niovewid = 0.2i 

box; nerve; box; move; box 

.FE 

gives 



You may, if you like, enter dimensions right on the .PS line. If you 
want a picture four inches wide, for example, you would follow your .PS 
with a 4. pic will understand you mean inches and make the whole picture 
four inches wide, preserving the scale of the default picture. Let's look at 
the default picture first. Here is the input: 

.PS 

circle; arrcw; box 
And now the output: 



Next, let's see the same picture blown up to a width of four inches: 
.PS 4 

circle; arrcw; bcx 
.FE 

will give you 
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Changing Default Sizes 




pic works internally in what it thinks are inches. Setting the variable 
scale to some value causes all dimensions to be scaled down according to 
that value. Thus, for example, scale»2.54 causes dimensions to be inter- 
preted as centimeters. 

The number given as a width in the .PS line overrides the dimensions 
given in the picture; this can be used to force a picture to a particular size 
even when coordinates have been given in inches. Experience indicates 
that the easiest way to get a picture of the right size is to enter its dimen- 
sions (in inches), then if necessary add a width to the .PS line. 
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Lines and Splines 



You have now seen seven pic forms: line, arrow, arc, circle, ellipse, box 
and move. One remains. You might approximate it with the knowledge 
you've accumulated. Input comprised of these familiar instructions: 

.PS 

liiie; arc; arc cw; arrow 
.PE 

would give you an acceptable spline: 




The spline tells us something useful about the pic language. The pic line, 
as the preceding example demonstrates, is more than a short (or even long), 
straight segment. It can unfold and turn before you according to your 
instructions: 

.PS 

line right 1i then down .5i left 1i then right 1i 
.FE 

The result suggests the rambling potential of the pic line: 




As their names suggest, lines and splines are similar to one another. 
Had you substituted the word spline for line in the example above: 

.PS 

spline ri^^t 1i then down .5i left 11 then ri^t 1i 
.FB 

you would have gotten this: 
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The following overlay provides a graphic comparison between the two: 

.PS 

ll2ie dashed ri^^ 1i then down .5i left 1i then right 1i 
spline froQ start of last line \ 

rig^it 1i then down .5i left 1i then ri?^t 1i 
.PE 

The result follows: 




Long input lines can be split by ending each partial line with a backslash, 
escaping the newline. 

Arrowheads may only be put on the ends of a line or spline. 
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Controlling Positions 



You can place things anywhere you want; pic provides a variety of ways 
to talk about places. As you have seen, pic accepts fairly straightforward 
instructions like up, down, right, and left with line and move. Thus 



.PS 2 

box ht 0.2 vdd 0.2 at 0,0 "1" 
move to 0.5,0 
box "2" 
move same 
box "3" 



# ueike picture two iiiches wide. 

# draw a .2" X .2" square 

# mcfve right 0.5 

# use same dimensions as last box 

# use same motion as before 



draws three boxes, like this: 



□ □ □ 

Notice the use of same to repeat the previous dimensions instead of 
reverting to the default values. And notice the lines beginning with "#." 
These comment lines are used to record your intentions in case you forget 
what you were drawing. They are discarded during processing and will not 
print. They begin with a pound sign (#) and end at the end of the line. 

For a more precise method of charting positions, pic also uses a standard 
Cartesian coordinate system, so any point or object has an x and y position. 
The first object is placed with its start at position 0,0 by default. The jc,y 
position of a box, circle or ellipse is its geometrical center; the position of a 
line or motion is its beginning; the position of an arc is the center of the 
corresponding circle. 

Position modifiers like from, to, by, and at are followed by an x,y pair 
and can be attached to boxes, circles, lines, motions, and so on to specify or 
modify a position. 
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Controlling Positions 



Attributes like ht and wid and positions like at can be written out in 
any order. So 

box ht 0.2 wid 0.2 at 0,0 
box at 0,0 wid 0.2 ht 0.2 
box ht 0.2 at 0,0 wid 0.2 

are all equivalent, though the last is harder to read and thus less desirable. 

The from and to attributes are particularly useful with arcs, to specify 
the beginning and ending points. By default, arcs are drawn counterclock- 
wise, 

arc frcro 0.5i,0 to 0,0. 5i 
is the short arc, and 

arc from 0,0. 5i to 0.5i,0 
is the long one: 



If the from attribute is omitted, the arc starts where you are now and goes 
to the point given by to. The radius can be increased or diminished to 
make flatter or tighter arcs. To form a flat arc like this one: 



you would use a radius of fifteen inches: 

arc -> cw from 0,0 to 2i,0 rad 15i 

You may not want this graph-paper level of precision, but it is nonethe- 
less at your disposal. Typifying the DOCUMENTER'S WORKBENCH Software 
family of tools, pic puts as much control into your hands as would like to 
assume. 
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Mapping and Naming pic's Forms 

Objects can be labelled or named so that you can talk about them later. 
For example. 




Bok1: 



bcjx ... 

# . . . other stuff . . . 
move to Box1 




Placenames have to begin with an upper-case letter (to distinguish them 
from variable names, which begin with lower-case letters). The name refers 
to the "center" of the object, which is the geometric center for most things. 
It's the beginning for lines and motions. 

Other combinations also work: 




line from Box1 to Bax2 

trove to Boxl \:qp 0.1 right 0.2 

roove to Boicl + 0.2»0.1 # same as previous 

line to BoicI - 0.5,0 




The reserved name Here may be used to record the current position of some 
object, for example as 

Box1 : Here 
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Mapping and Naming pic's Forms 



Labels can function as variables — they can be reset several times in a 
single picture, so a line of the form 

Bax1: Box1 + 1i,1i 

is perfectly legal. 

You can also refer to previously drawn objects of each type, using the 
word last. For example, if we began with the following input: 

box "A"; circle "B"; box "C" 

then last box refers to box C, last circle refers to circle B, and 2nd last box 
refers to box A. Numbering of objects can also be done from the beginning, 
so boxes A and C are 1st box and 2nd box respectively. 

To cut down the need for explicit coordinates, most objects can be 
described using compass points: 

B.n 



B.nw 



B.w 



B.sw 



B.ne 




B.se 



The primary compass points may also be written as .r, .b. A, and .t, for 
right, bottom, left, and top. The box above was produced with 
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Mapping and Naming pic's Forms 




B: iXDX "B.c" 
" B.e" at B.e ljust 
" B.ne" at B.ne ljust 
" B.se" at B.se ljust 
"B.s" at B.s below 
"B.n" at B.n above 
"B.sw " at B.sw rjust 
"B.w " at B.w rjust 
"B.nw " at B.iw rjust 




Note the use of ljust rjust, above, and below to adjust the positioning of 
the inserted text, and note the blank space used within the double quotes to 
move text away from the box's vertical lines. 

Normally, text is centered at the geometric center of the object with 
which it is associated. The attribute ljust causes the left end to be at the 
specified point (which means that the text lies to the right of the specified 
place), and rjust puts the right end at the place, above and below center 
the text one half line space in the given direction. 

You may not combine text attributes. It is illegal, for instance, to say 
'fexf • above ljust. 

Text is most often an attribute of some other object, but you can also 
have self-standing text: 

"this is scroe text" at 1,2 ljust 

Lines and arrows have a start, an end, and a center in addition to 
corners. There are many ways to talk about the corners of an object. 
Besides the compass points, almost any sensible combination of left, right, 
top, bottom, upper, and lower will work. Furthermore, if you don't like 
the shorthand notation of compass points, as in 

last boK.ne 

you can instead say 

upper right of last bc3x 
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Mapping and Naming pic's Forms 



A longer statement like 

.PS 

line fran upper left of 2nd last bcoL to bottom of 3rd last ellipse 
.FE 

begins to wear after a while, but it is descriptive. 

It is sometimes easiest to position objects by positioning some part of 
one at some part of another, for example the northwest corner of one at the 
southeast corner of another. The with attribute in pic permits this kind of 
positioning. For example, 

.PS 

bcDC ht 0.75i wid 0.751 

box ht 0.51 vdd 0.51 with .sw at last bcac.se 
.PE 

produces 



Notice that the corner after with is written .sw 
As another example, consider 

.PS 

ellipse; ellipse with .nw at last ellipse.se 
.PE 

which makes 
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Mapping and Naming pic*8 Forms 



Sometimes it is desirable to have a line intersect a circle at a point 
which is not one of the eight compass points that pic knows about. In such 
cases, the proper visual effect can be obtained by using the attribute chop to 
chop off part of the line. 




circle "a" 



circle "b" at 1st circle - (0,75i, 1i) 
circle V at 1st circle + (0,75i, -1i) 
line from 1st circle to 2nd circle chop 




By default the line is chopped by circlerad at each end. This may be 
changed: 

line . . . chop r 
chops both ends by r, and 

line • • . chop rl chop r2 

chops the beginning by rl and the end by rl 

There is one other form of positioning that is sometimes useful, to refer 
to a point some fraction of the way between two other points. This can be 
expressed in pic as 

fraction of the way between positionl and positionZ 
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Mapping and Naming pic's Forms 



fraction is any expression, and positionl and position2 are any positions. 
You can abbreviate this phrase; "of the way" is optional, and the whole 
thing can be written instead as 

fraction < positionl , position2 > 

As an example, 

.PS 
box 

arrow right from 1/3 of the way between last box.ne and last bC3x.se 

arrow right from 2/3 <last box.ne, last box.se> 

.PE 

produces 



Naturally, the distance given by fraction can be greater than 1 or less than 
0. 
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Blocks 



Any sequence of pic statements may be enclosed in brackets [...] to form 
a block, which can then be treated as a single object and manipulated rather 
like an ordinary box. For example, if we say 

,PS 

box "1" 

[ box "2"; arrow "3" above; box. "4" ] with .n at last box.s - (0,0.1) 

"thing" at last [],s 

.PE 

we get 





1 




2 


3 


4 


» 

thing 



Notice that last-type constructs treat blocks as a unit and don't look inside 
for objects: last box.s refers to box 1, not box 2 or 4. You can use last [] , 
etc., just like last box . 

Blocks have the same compass corners as boxes (determined by the 
bounding box). It is also possible to position a block by placing either an 
absolute coordinate (like 0,0) or an internal label (like A) at some external 
point, as in 

[ . • . ; A: . . . ; ... ] with .A at ... 

Blocks join with other things like boxes do (i.e., at the center of the 
appropriate side). 

Names of variables and places within a block are local to that block, and 
thus do not affect variables and places of the same name outside. You can 
get at the internal place names with constructs like 

last [].A 

or 

B.A 
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" ' ' Blocks 

where B is a name attached to a block like so: 

B * [ • • • \ Al • • • 9 ] 

When combined with define statements (next section), blocks provide a rea- 
sonable simulation of a procedure mechanism. 

Although blocks nest, it is possible to look only one level deep with 
constructs like B.A although A may be further qualified (i.e., B.A.sw or top 
of B.A are legal). 

The following example illustrates most of the points made above about 
how blocks work. 
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Blocks 



.PS 
h = 
dh = 
dw = 
[ 



.5i 
.021 
.11 



Ptr: t 



bGocht - h; booodd s dw 
A: bGK 
B: bcoc 
C: bcK 

booc wid 2#bcawid 
D: bGK 



] 

Block: [ 



bCBdit = 2«dw; bcDCMld = 2«dw 
ncrvewld - 2«dh 
A: box; move 



wid 2*baxwld; move 



B: box; move 
C: box; move 
box invis " , 
D: box 

] with .t at Ptr.s - (0,h/2) 
arxow fron Ptr .A to Block.A.nw 
anxM from Ptr.B to Blodc.B.nw 
arrow from Ptr.C to Block.C.nw 
arrow from Ptr.D to Block.D.nw 

] 

box dashed ht last [].ht4<iw wid last [].wid+dw at last [] 
.FE 



This produces 
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Variables and Expressions 



It's generally a bad idea to write everything in absolute coordinates if 
you are likely to change things. Different size pages are likely to make you 
wish for proportional measures, pic variables enable you to change the pic- 
tures you make without much ado. 



a = 0.5; b = 1 

box wid a ht b 

ellipse wid a/2 ht 1.5*b 




Expressions may use the standard arithmetic operators +, /, and % 
for adding, subtracting, multiplying, dividing, or determining a modulus. 
Parentheses may be used to group operations. The logical operators ==, !=, 
>/ </ ^/ ^/ &&, and I are allowed as well as the assignment operator, 

Probably the most important variables are the predefined ones for con- 
trolling the default sizes of objects. These may be set at any time in any 
picture and retain their values until reset. 

You can use the height, width, radius, and x and y coordinates of any 
object or corner in an expression: 








BgkI.x 
Boxl.ne.y 
Bqk1 .wid 
BoKl.ht 

2nd last circle. rad 



# the X coordinate of Bax1 

# the y ooordmate of the NE comer of Bcdc1 

# the width of Bax1 

# and its height 

# the radius of the 2nd last circle 
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Variables and Expressions 



Any pair of expressions enclosed in parentheses defines a position; 
furthermore, such positions can be added or subtracted to yield new posi- 
tions: 

( a: , y ) 
(^i/yi)+(^2/y2) 

If pi and p2 are positions, then (pi,p2) refers to the point 
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Macros 



pic provides a rudimentary macro facility, the simple form of which is 
identical to that in eqn: 

define name X replacement text X 

defines name to be the replacement text; X or any character that does not 
appear in the replacement may be used as a delimiting character. Any sub- 
sequent occurrence of name will be replaced by replacement text. 

Macros with arguments are also available. The replacement text of a 
macro definition may contain occurrences of $1 through $9 ; these will be 
replaced by the corresponding actual arguments when the macro is invoked. 
The invocation for a macro with arguments is 

narBe(arg1, arg2, ...) 

Non-existent arguments are replaced by null strings. 

As an example, one might define a square by 

.PS 

define square X box ht $1 wid $1 $2 X 
.PB 

Then 

.PS 

squared!, "one" "ijich") 
.FE 

calls for a one-inch square with the obvious label, and 
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Macros 



.PS 

squaredi, "one" "inch") 
.PE 

calls for a square with no label: 







one 
inch 









Coordinates like x,y may be enclosed in parentheses, as in {x,y), so they can 
be included in a macro argument. 
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copy and copy...thru Facilities 



pic offers a facility similar to macros in that it allows you to take input 
from a remote source. You use this facility with the instruction copy, which 
copies data from the file you give it as an argument. Here's how it works: 




When pic gets to the line beginning copy, it reads the contents of the file 
for its data. It ignores .PS's and .PE's in the remote file, so you can incor- 
porate smaller, already drawn pictures into larger ones. 

A slight refinement of this usage is the 

oppy ^*file" thru macro-name 

copies file, treating each line as an invocation of the named macro (each 
field being an argument). A literal macro may be used instead of a name: 

copy "/z7e" thru X macro replacement text X 

and if no file name is given, the remainder of the input until the next •?£ is 
used. So to plot a set of circles at points whose coordinates and radii come 
from a file: 
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copy and copy...thni Facllitios 




oap^ thru / cdxde rad $3 at $1,$2 / 

.05 

1 1 .1 




Here are the results: 




o O 

The sh command executes an arbitrary UNIX system command line: 

.PS 

sh X anything X 
,F& 

as with the macro facility, X is any character not in anything.. 
A last touch to the thru instruction is until: 

.PS 

oc^ thru macro until "string** 
.PE 
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copy and copy...thni Facilities 



csopy pie thru macro until "string" 
.PE 

That is, you are able to specify how much of the remote macro or remote 
file you want to read as input. When pic sees string, whatever you specify it 
to be, pic ceases to use macro or file as input. 
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Loops and Conditional Statements 

pic provides an if statement and a for loop: 



.PS 

.ps -2 

pi s atazi2(0,-1) # ataii2 is a pic expression, 

for i = 0to2*pib/0.1doX 

"s" at i. sin(i) 
"c" at i, oos(i) 

X 

.ps *2 
.FE 



The processed output follows: 

The body of the loop is delimited by any character not found within it. The 
by clause is optional; values may be preceded by any of the four basic arith- 
metic operators: 

+ (addition) 

- (subtraction) 

♦ (multiplication) 

/ (division) 

The if statement is 

if expression then X anything X else X anything X 

where the else clause is optional. The expression may use the usual rela- 
tional operators: 
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Loops and Conditional Statements 






(equal to) 




(not equal to) 


> 


(greater than) 


>= 


(greater than or equal to) 


< 


(less than) 


<= 


(less than or equal to) 


&& 


(and) 


1 


(or) 




(not) 



For example, the following pic file: 



.PS 

for i = OtopilDyO,iaoX 

s = sin(i) 

if s > 0.8 then Y s = 0.8 Y 
"x" at i/2, s/2 

X 

.EE 



produces the following: 

^XXXXXXXXXXXXXXx, 




A string comparison using == or != is also permitted: 
if stringl == string! then . . . 
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Technical Discussion 

pic is a troff preprocessor. The command line you use to run it reflects 
this relationship with troff: 

pic file I troff —mm | typesetter 

If eqn is also present, make sure eqn follows pic in the order of processing: 

pic file I eqn | troff —mm | typesetter 

pic copies the .PS and .PE lines from input to output intact, except that 
it adds two things on the same line as the .PS. Type: 

.PS wh 

in order to specify h and w as the picture's height and width in inches. 

If .PF is used instead of .PE, the position after printing is restored to 
where it was before the picture started, instead of being at the bottom. (F is 
for "flyback.") 

Any input line that begins with a period is assumed to be a troff 
request or macro and is interpreted at that point. Adding vertical space (\v) 
or extra spaces (.sp) will probably affect the outcome of your pictures. Point 
size and font changes are generally harmless, though. Consider the follow- 
ing file: 



.ps 24 

circle radius .4 at 0,0 
.ps 12 

circle radius .2 at 0,0 
.ps 8 

circle radius .1 at 0,0 
.ps 6 

circle radius .05 at 0,0 

.ps 10 \" don't forget to restore point size 







which produces this picture: 
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Technical Discussion 




pic does preserve the state of troff's fill mode across pictures. 

It is also safe to include sizes, fonts and local motions within quoted 
strings ( ) in pic, so long as whatever changes are made are unmade 
before exiting the string. For example, to print text in italic two points 
larger: 

.PS 

ellipse "\s+2\fIStodlel\fF^2" 
.FE 

results in the following: 



This is essentially the same rule as applies in eqn. 

There is a subtle problem with complicated equations inside pic pictures 
— they come out wrong if eqn has to leave extra vertical space for the equa- 
tion. If your equation involves more than subscripts and superscripts, you 
must add to the beginning of each equation the extra information "space 0". 
The following file: 
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Technical Discussion 




bofldit=0.75 
arzcw 

box "Sspace {H( ooega )} cn^ {1 - H( coaega )}$" 

arrow 

lxQ{ht=0,5 

.FE 




produces this: 









^ 


1-H(«) 


»• 



pic output is specified in inches and is, therefore, independent of any 
particular typesetter. In the rare case that you have to specify your 
typesetter, use the — T option as in 

pic —Taps ... 

for the Autologic APS-5 phototypesetter. 



Pictures 

The top-level object in pic is the "picture": 
picture: 

.PS optional-width optional-height 

element-list 

.PE 

If optional-width is present, the picture is made that many inches wide, 
regardless of any dimensions used internally. The height is scaled in the 
same proportion unless optional-height is present. 



44 USER'S GUIDE 



Technical Discussion 



If .PF is used instead of .PE, the position after printing is restored to 
what it was upon entry. 



Elements 

An element-list is a Ust of elements; the elements are 

shape attribute-list 
placename : element 
placename : position 
variable « expression 
direction 

[ list of elements } 
[ list of elements ] 
for statement 
if statement 
copy statement 
print statement 
plot statement 
sh X commandline X 
troff-command 

Specify a placename with a capital letter 
followed by zero or more letters or numbers. 

Specify a variable with a letter 
followed by zero or more letters or numbers. 

Elements in a list must be separated by newlines or semicolons; a long 
element may be continued by ending the line with a backslash. Comments 
are introduced by a # and terminated by a newline. 

Variable names begin with a lower case letter; place names begin with 
upper case. Place and variable names retain their values from one picture 
to the next. 

The current position and direction of motion are saved upon entry to a 
{•„} block and restored upon exit. 
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Technical Discussion 



Elements within a block enclosed in [...] are treated as a unit; the 
dimensions are determined by the extreme points of the contained objects. 
Names, variables, and direction of motion within a block are local to that 
block. 

trojf-cotnmand is any line that begins with a period. Such lines are 
assumed to make sense in the context where they appear; accordingly, if it 
doesn't work, don't call. 



Primitives 

The primitive objects are 

primitive: 

box 

circle 

ellipse 

arc 

line 

arrow 

spline 

move 

text'list 

arrow is a synonym for line — >• 



Attributes 

An attribute-list is a sequence of zero or more attributes; each attribute 
consists of a keyword, perhaps followed by a value. In the following, e is 
an expression and opt-e an optional expression. 
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attribute: 



h(eigh)t e 
rad(ius) e 
up opt-e 
right opt-e 
from position 
at position 
by e, e 
dotted opt-e 
chop opt—e 
invis 
text-list 



wid(th) e 
diam(eter) e 
down opt-e 
left opt-e 
to position 
with corner 
then 

dashed opt-e 
-> <- <- 



same 



> 



Missing attributes and values are filled in from defaults. Not all attri- 
butes make sense for all primitives; irrelevant ones are silently ignored. 
These are the currently meaningful attributes: 

box: 

height, width, at, same, dotted, dashed, invis, text 
circle, ellipse: 

radius, diameter, height, width, at, same, invis, text 

arc: 

up, down, left, right, height, width, from, to, at, radius, 
invis, cw, <—,->, < — >, text 
line, arrow 

up, down, left, right, height, width, from, to, by, then, at, 
same, dotted, dashed, invis, <—,—>, <— >, text 

spline: 

up, down, left, right, height, width, from, to, by, then, at, 
same, invis, <-,->, <->, text 

move: 

up, down, left, right, to, by, same, text 

text-list: 

at, text-item 

The attribute at implies placing the geometrical center at the specified place. 
For lines, splines and arcs, height and width refer to arrowhead size. 
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Text 

Text is normally an attribute of some primitive; by default it is placed at 
the geometrical center of the object. Stand-alone text is also permitted. A 
text'list is a list of text items; a text item is a quoted string optionally fol- 
lowed by a positioning request: 

text-item: 

n II 

center 

ljust 

rjust 

above 

below 

If there are multiple text items for some primitive, they are centered verti- 
cally except as qualified. Positioning requests apply to each item indepen- 
dently. 

Text items can contain troff commands for size and font changes, local 
motions, etc., but make sure that these are balanced so that the entering 
state is restored before exiting. 



Positions and Places 

A position is ultimately an x,y coordinate pair, but it may be specified in 
other ways. 

position: 

place 

( position ) 

expression, expression 

( position ) [± (expression, expression)] 

( position ) [± expression, expression] 

( placet, place! ), i.e., ( placel^x, placel.y) 

expression < position , position > 

expression [of the wayj between position and position 
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place: 

placename [corner] 
corner placename 
Here 

corner of nth shape 
nth shape [corner] 

A corner is one of the eight compass points or the center or the start or end 
of a primitive. 

corner: 

.n .e .w .s .ne .se ,nw .sw 
.t .b .r .1 
.c .start .end 

Each object in a picture has an ordinal number; nth refers to this. 
nth: 

nth 

nth last 

Since pic is flexible enough to accept names like 1th and 3th, synonyms like 
1st and 3st are accepted as well. 



Variables 

The built-in variables and their default values are: 

arcrad = 0.25 circlerad«0.25 

arrowwid = 0.05 arrowht = 0.1 (arrowhead dimensions) 

boxwid = 0.75 boxht = 0.5 

ellipsewid « 0.75 ellipseht = 0.5 

linewid = 0.5 lineht = 0.5 

movewid = 0.5 moveht = 0,5 

textwid = textht = 

dashwid = 0.05 scale = 1 

These may be changed at any time, and the new values remain in force 
from picture to picture until changed again. 
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The variable textht and textwid may be set to any values to control 
positioning. The width and height of the generated picture may be set 
independently from the .PS line. Variables changed within Y ^rid revert 
to their previous value upon exit from the block. Dimensions are divided 
by scale during output. 



Expressions 

Expressions in pic are evaluated in floating point. All numbers 
representing dimensions are taken to be in inches. 

expression: 

e + e 
e — e 
e * e 
e I e 

e % e (modulus) 

— e 

(e) 

variable 
number 
place .X 
place .y 
place .ht 
place .wid 
place .rad 

sin(e) cos{e) atan2(e,e) log(^) sqrt(e) int(^) 
max(e,e) min{e,e) rand(e) 



Logical Operators 

pic provides the following operators for logical evaluation: 
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> 
< 



(not) 

(greater than) 
(less than) 

(greater than or equal to) 
(less than or equal to) 



&& (and) 

I (or) 

== (equal to) 

!= (not equal to) 



Definitions 

The define statement is not part of the grammar, 
define: 



Occurrences of $1, $2, etc., in replacement text will be replaced by the 
corresponding arguments if name is invoked as 

naive(argl, argl, ...) 

Non-existent arguments are replaced by null strings. Replacement text may 
contain newlines. 



copy and copy...thru Statements 

The copy statement includes data from a remote file or data immediately 
following copy in the pic file: 

copy "file" 

copy thru macro 

copy "file" thru macro 

copy "file** thru macro until **string" 

The macro may be either the name of a defined macro, or the body of a 
macro enclosed in some character not part of the body. If no file is given, 
copy copies the input until the next .PE. 



define name X replacement text X 
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for Loops and if Statements 

The for and if statements provide for loops and decision-making: 

for var=expr to expr by expr do X anything X 
if expr then X anything X else X anything X 

The by and else clauses are optional. The expr in an if may use the usual 
relational operators or the string tests strl (or !=) strl. 

Miscellany 

The sh command executes a command line: 
sh X commandline X 

It is possible to plot the value of an expression: 

plot expr opt-format attributes 

The expr is evaluated and converted to a string (using the format 
specification if provided). 

The state of fill or no-fill mode is preserved around a picture. 

Input numbers may be expressed in E notation. 
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.PS 

define ndblock X 

box wid ba)cwid/2 ht bGExht/2 

dawn; bcsc saioQ with .t at botton of last box; box same 

X 

boodxt = ,2i; baxwid = .3i; circlerad = .3i 
down; box; box; box; box ht 3»boodit 

L: box; box; box xnvis wid 2»baxwid "hashtab:" with .e at 1st box .w 
right 

Start: box wid .5i with .swat 1st box.ne + (.4i,.2i) 
N1: box wid .2i "n1"; D1: baxwid .3i "d1" 
N3: baxwid .4i "n3"; D3: baxwid .3i "d3" 
box wid .4i 

N2: box wid .5i "n2"; D2: box wid .2i "d2*' 

arrow right from 2nd box 

ndblock 

spline -> ri^it .2i frcm 3rd last box then to Nl.sw (0.05i,0) 
spline -> ri^it ,3i from 2nd last box then to D1.sw * (0.05i,0) 
arrow right f ran last box 
ndblock 

spline -> ri^ .2i frcm 3rd last box to N2.sw-{0,05i, .2i) to N2.sw+(0.05i,0) 
spline -> ri^it .3i frcro 2nd last box to D2.sw-(0.05i, .2i) to D2.sw+(0.05i,0) 
arrow right 2*linewid from L 
ndblock 

spline -> right .2i from 3rd last box to N3.sw + (0.05i,0) 
spline -> ric^t .3i frcm 2nd last box to D3.sw + (0.05i,0) 
circle invis "ndblock" at last box.e + (.7i,.2i) 
arrow dotted frcm last circle to last box chop 
box invis wid 2*b0ixwid "ndtable:" with .e at Start. w 
, .FE 
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.FS 4.8 
.p6 8 
baxht S.5 
bOQCwid S.5 
circlerad » .25 



arrow "source" "code" 
lA: box "lexical" "analyzer" 

arrow "tcScens" above 
P: box "parser" 

arrow "iixtennediate" "code" 
Sem: box "semantic" "checker" 

arrow 



arrcw <-> up from top of LA 
liC: box "lexical" "corrector" 

arrow <~> i:^ f ran top of P 
Syn: box "syntactic" "corrector" 

arrow up 

DMP: box "diagnostic" "message" "printer" 

arrow <-> rig^t from ric^t of EMP 

ST: box "syicbol" "table" 

arrow frooi DC.ne to EMP.sw 
arrow fran San.nw to EKP.se 
arrow <-> fran Sem.top to ST.bot 
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diagnostic 
message 
printer 




symbol 












^ ^ 


table 












1 


\ 




J 
/ 








lexical 




syntactic 












corrector 




corrector 












\ 


\ 
1 




1 
\ 


\ 
1 




\ 


1 




source 


lexical 


tokens 
^ 


parser 


intermediate 


semantic 




code ^ 


analyzer 




code " 


checker 


> 
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circle "DISK" 

arrow "character" "defns" 

box "CPU" "{16-bit nrlni)" 

{ arrow <- from top of last box up "input " rjust } 
arrcw 

CRT: " CBT" ljust 

line fran COT - 0,0.075 up 0.15 \ 

then right 0.5 \ 

then rig^t 0.5 up 0.25 \ 

then down 0.5+0.15 \ 

then left 0.5 \xp 0.25 \ 

then left 0.5 

Paper: CRT + 1.0+0.05,0 
arrow from Ps^ier + 0,0.75 to Paper - 0,0.5 
{ move to start of last arrow dam 0.25 
{ move left 0.015; circle rad 0.05 } 

{ move ric^ 0.015; circle rad 0.05; " rollers" ljust } 

} 

" paper" ljust at end of last arrow ric^t 0.25 vqp 0,25 
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operators ... 33, 40, 51-52 

plot ... 16, 37, 45, 52 

position ... 15, 22-24, 26-30, 34, 42, 
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preprocessor ... 1, 42 
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requests ... 2-3, 42, 48 



reserved name ... 24 
sh command ... 38, 45, 52 
size ... 9, 13, 17, 19, 33, 42, 47-48 
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troff ... 1-3, 6, 42-43, 48 
typesetter ... 2, 42, 44 
variables ... 9, 11-12, 17, 19, 24-25, 
30, 33, 45-46, 49-50 



THE PREPROCESSOR pic 59 



Table of Contents 



Introduction 
Basics 

Fine-tuning the Details 

Combining Different Statistics 

Expressing Exponential Values 

Manual Drawing 

Macros 

copy thru 

Multiple Coordinates 

for Loops and if Statements 

grap Sampler 

Index 



1 

2 
9 
12 
15 
18 
21 
24 
26 
28 
30 
48 

THE PREPROCESSOR grap i 



Introduction 



This tutorial is intended to give you a working knowledge of grap, the 
DOCUMENTER'S WORKBENCH Software tool for making graphs. It will also 
introduce you to grap's programmable features. With this knowledge you 
will be able to represent statistics in graphs that can be automatic or mani- 
pulated using programming features. You will also learn how to implement 
features, such as loops and conditional statements, for handling information 
in sophisticated ways. 

You should be familiar with the following concepts and tools to benefit 
fully from this tutorial. 

■ You should know how to use a UNIX System V text editor 
(ed, vi, and ex are examples). See the UNIX System V User 
Guide, 

■ You should know what a file and directory are and know 
how to manipulate them. See the UNIX System V User Guide. 

■ You should know how to redirect input and output using 
pipes. See the UNIX System V User Guide, 

■ You should be familiar with a UNIX System V formatter 
(nroff or troff). See the tutorials in this book that discuss 
nroff or troff. 

■ Your understanding of grap would be assisted by a 
knowledge of pic though this is not essential. To learn about 
pic, see "The Preprocessor pic: A Tutorial" in this book. 
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Basics 

To chart lists of numbers, grap is largely automatic. It will take a list of 
figures with no further information and draw a box, draw tick marks that 
represent the range of values suggested by the numbers, and plot the 
numbers according to their values. For more detailed tasks, its requirements 
are modest. In the workarea between its .Gl and .G2, it accepts special for- 
matting instructions stating the size of the graph (though grap will give 
you a default graph size of two inches high by three inches wide), for speci- 
fying tick mark intervals (though grap will infer these from your numbers), 
for placing labels along axes, and for providing other details concerning the 
graph's presentation. It then reads a list of numbers and plots them in con- 
formance wijh the specifications you have stated. While grap, like pic, 
offers sophisticated features, such as proportional scaling, macros, a 
copy...thru facility, a looping facility, and the ability to evaluate conditional 
statements, it is also a concise and easy-to-learn language. The following 
example suggests its streamlined form. 

This graph of the 1984 age distribution in the United States 



5 



Population 
(in millions) 



4- 



3- 



1 - 












20 



40 

1984 Age 



60 



80 



was produced by these grap instructions: 
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.G1 

coord X 0,89 y 0,5 

label left "Population" "(in millions)" 
label bottom "1984 Age" 
draw solid 
copy "pc5).cp" 
.G2 



The second line, giving coordinates, dictates the graph's range of tick 
marks along the x and y axes. The next two lines, beginning label, allow 
for the introduction of text to explain the graph. Notice the language you 
use to enter labels: left side, bottom of picture, etc. The next line calls for a 
solid line to be drawn, charting the peaks and valleys of U. S. age distribu- 
tion. Omitting draw solid would have given you scattered points for each 
age group. Finally, copy asks that grap look for its numbers in a file called 
popxp. The file contains two simple columns: 1) an ordered numerical 
sequence of ascending ages from new-born to eighty-nine and 2) the 
number of living Americans in these age groups. 

The grap preprocessor works in concert with pic and troff as the follow- 
ing typical grap command line illustrates: 

grap file \ pic | troff -mm | typesetter 

grap converts all instructions between .Gl and .G2 into pic instructions; pic 
converts them into input for troff; and troff processes them along with the 
remainder of the file's text and formatting commands. 

Let's see what grap does with a simple list of dates. The following is a 
list of ten different years: 
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1943 
1959 
1964 
1977 
1985 
1998 
2001 
2024 




Given to grap, the data is interpreted into the following graph: 



2000- 



1950- 



5 10 



grap examined the figures and determined two salient features before 
labeling the x and y axes. First, it counted the number of items, and second, 
it found the range of values expressed by the dates. In each case, grap 
decided upon sensible intervals with which to mark the information. The 
dates themselves are given as a series of scattered plotting marks. 
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The following grap example is more fast-paced, graphically displaying 
the winning times of Olympic runners. Here's the graph: 



50- 



45- 



5 10 15 20 

It demonstrates the generally decreasing winning times from 54.2 seconds 
to 44.60 seconds. Here's how it was done: 




54.2 
49.4 
49.2 
50.0 
48.2 



The single number on each line is the winning time in seconds for the 
men's 400 meter run, from the first modern Olympic Games (1896) to the 
nineteenth (1980). This file of winning times, olymp.g, would be processed 
as follows: 

grap olymp.g | pic | troff | typesetter 
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This tutorial will frequently give only the first five lines and the last 
line of data. Omitted lines are indicated by 

There are a couple of things especially worth noticing in the olymp.g 
file. First, the coord line, present in the first example, is missing here, grap 
is able to adjust its presentation of your numbers automatically into a rea- 
sonably proportioned graph. What is more, it automatically provides the 
ticks along its axes, inferring them from your numbers. Second, without 
the draw solid instructions, the graph is presented using scattered points 
rather than a climbing and falling line. 

If the winning times represented above were contained in the file 
times.cp, you could produce the same graph with the program: 

.G1 

copy "tames. cp" 
.62 

That is, copy "times.cp" is equivalent to including the data itself between 
the .Gl and .G2 macros, copy requires the file's name to be surrounded by 
double quotes (just as label requires its labels to be in double quotes.) 

A variant of the file times-cp is the following file, mtimes.cp. This file 
contains two columns. In effect the first column (the Olympic year) pushed 
over the second column (the winning times): 




1896 54.2 
1900 49.4 
1904 49,2 
1908 50.0 
1912 48.2 



1980 44.6 



If you plot these data with the following program: 
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.G1 

ooipy "ratines. cp" 
.G2 

you produce the following graph: 



50- 



45- 



1900 1920 1940 1960 1980 

The file's first column, as you can see, gives the information that will be 
spelled out along the x axis. Because no Olympic games were held during 
wartime (1916, 1940, 1944), no data for these years are included in 
mtimes.cp. This is reflected in the graph by an absence of points for these 
A:-axis values. 

Because the previous data (in times.cp) had just one number per line, 
grap viewed it as a time series and supplied x-values of 1, 2, 3, ... before 
plotting the data as y-values. The input to the second program has two 
values per line, so they are interpreted as {x, y) pairs. 

Rather than a scatter plot of points, you might prefer to see the winning 
times connected by a solid line. The program 
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Fine-tuning the Details 



You can make the graph more attractive by modifying its frame and 
adding labels: 




"H I \ 1 T" 

1900 1920 1940 1960 1980 

Olympic 400 Meter Run: Winning Times 



These details were added with the following lines: 

f ^ 

.G1 

frame invis ht 2 wid 3 left solid bot solid 

label left "Tiine" "(in seconas)" 

label bot "01yn9>ic 400 Meter Run: Winning Times" 

draw solid 

copy "ratimes.cp" 

y 

The frame instruction describes the graph's bounding box: the overall 
frame (which has four sides) is invisible; its height is two inches, and its 
width is three inches (no change from default sizes for height and width); 
and the left and bottom sides are solid (they could have been dashed or 
dotted instead). The labels appear on the left and bottom, as requested. 
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To set the range of each axis, grap examines the data and pads both 
dimensions by seven percent at each end. The coord (coordinates) line, as 
you saw in the opening example, allows you to specify the range of one or 
both axes explicitly. That is, it turns off automatic padding: 



.G1 

frame Invis ht 2 wid 3 left solid bc7t solid 
label left "Time" "(in seocaads)" 
label bot "Olyoopic 400 Meter Run: Wiisiin? Times" 
ocxcd X 1694,1982 y 42, 56 
draw solid 
oapy "mtimes.cp" 
.62 



The y-axis now ranges from 42 to 56 seconds (a little more than before), and 
the X-axis from 1894 to 1982 (a little less): 



55- 



Time 



50- 



(in seconds) 



45- 



— I \ 1 \ r 

1900 1920 1940 1960 1980 
Olympic 400 Meter Run: Winning Times 



The ticks in the preceding graphs were generated by graphs guessing at 
reasonable values. If you would rather provide your own, you may use the 
ticks instructions, which come in the two varieties illustrated below: 
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frame invls ht 2 wid 3 left solid bot solid 
label left "Time" "(in secGnds)" left .2 
label bot "Olynpic 400 Meter Run: Wiimang Tiines" 
coord X 1894,1982 y 42, 56 

ticks left out at 44 "44", 46 , 48 "48", 50, 52 "52", 54 
ticks bot in frcm 1900 to 1980 by 20 
draw solid 
copy "mtimes.cp" 



The first ticks instruction deals with the left axis: it puts the ticks fac- 
ing out at the numbers in the list, grap puts labels only at values with 
strings, except that when no labels at all are given, each number serves as 
its own label, as in the second ticks instruction. That line is for the bottom 
axis: it puts the ticks facing in at steps of 20 from 1900 to 1980. The 
instruction ticks off turns off all ticks, grap does its best to place labels 
appropriately, but it sometimes needs your help: the left .2 clause moves 
the left label 0.2 inches further left to avoid the new ticks. 





(in seconds) 



Time 



44- 



52- 




1900 



1920 



1940 



1960 



1980 



Olympic 400 Meter Run: Winning Times 
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The file wtimes.cp contains the times for the women's 400 meter race, 
which has been run only since 1964: 

1964 52 
1968 52 
1972 51.08 
1976 49.29 
1980 48.88 

Rather than redrawing an entirely different graph in order to include the 
women's times, you can use a grap instruction. To add these times to the 
graph, you use the instruction new: 




frame ixivis ht 2 wid 3 left soUd bot solid 
label left "Time" "(in seoandls)" left .2 
label bot "Olyns^dc 400 Meter Run: Winning Times" 
oooEd X 1894,1982 y 42, 56 

tides left out at 44 "44", 46, 48 "48", 50, 52 "52", 54 
tides bot iJi fran 1900 to 1980 by 20 
draw solid 
copy "mtim&s.cp" 
new dotted 
copy "wtimes.cp" 
"Wtinen" size -3 at 1958,52 
, "Men" size -3 at 1915,51 

y 

The instruction, new^ tells grap to end the old curve and start a new 
curve (which in this case will be drawn with a dotted line): 
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The text was placed on the graph with instructions of the form 

"string" at xvalue, yvalue 

The size clauses following the quoted strings tell grap to shrink the charac- 
ters by three points (absolute point sizes may also be specified). Strings are 
usually centered at the specified position but can be adjusted by clauses to 
be illustrated shortly. Consider the next graph as a brief introduction to the 
text adjustment feature. (Those of you who know pic will feel at home): 



52 

Time 
(in seconds) 



44 - 



1900 1920 1940 1960 1980 
Olympic 400 Meter Run: Winning Times 
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This version incorporates text to emphasize Eric Liddell's 1924 gold 
medal performance of 47.6 seconds. (Remember Chariots of Fire?) The graph 
itself is, of course, only slightly different than the one preceding it. In fact, 
only two lines have been added to the input file: 




frame litvis ht 2 wid 3 left solid bot solid 



"Men" size -3 at 1915,51 
bullet at 1924,47.6 

, "\flEric LiddellNfR " size 6 rjust at 1924,47.6 i 

X y 

These last two lines place a dot, or bullet, at the point of Liddell's win- 
ning time and place his name next to the bullet. There are a few details 
worth noticing here. First, markers like the bullet are not text and there- 
fore do not require double quotes. Second, Eric Liddell's name is specified 
to be set in an italic font with the escape sequence \f . Next, the size of the 
name is expressed as an absolute value, unlike its predecessors, which were 
set using relative values. Finally, using the instruction rjust, Liddell's name 
is adjusted to be set off slightly from the bullet. In addition, space has been 
apportioned inside the double quotes. 
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The file phone.cp records the number of telephones in the United States 
from 1900 to 1970: 

00 1.3 

01 1.8 

02 2.3 

03 2.8 

04 3.3 

70 120.2 

The file contains two columns of information: the first column is a list of 
years (given in abbreviated form); the second is a corresponding list of the 
number of U.S. telephones in service (given in millions, truncated to the 
nearest hundred thousand). The simple grap program 




.Gl 

copy "phcaie.cp" 
.G2 




produces the following graph: 
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150- 



100- 



50- 



0- 







20 



40 



60 



80 



The number of telephones appears to grow exponentially. To represent 
that different magnitude of growth, you can refine the simpler, preceding 
graph into a slightly more sophisticated one. Focusing on this expansion's 
exponential quality, you can use a logarithmic y-axis with which to plot the 
data. You do this by adding log y to the coord instruction. What is more, 
you could add label changes, more ticks, and a solid line to enhance the 
graph's appearance: 



label left "Millicns of" "Telephones" "(log scale)" left .5 
ooona X 0,70 y 1,130 log y 
ticks left out at 1, 2 , 5, 10 , 20, 50, 100 
ticks bot out at "1300", 70 "1970" 
ticks bot out from 10 to 60 by 10 "'96g" 
draw solid 
oopy "phone. cp" 




The third ticks instruction uses a string, %g, which provides a method 
for presenting text in a particular format. In the example above, the string 
is used to place an apostrophe before each number from 10 to 60. In effect 
%g represents each number to be printed in the given range. The string, 
'19%g", for example, would have produced the full, four-digit year for each 
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Expressing Exponential Values 



entry along the A:-axis. (Those readers who use the C Programming 
Language will recognize %g as a printf format string.) To suppress labels, 
use the empty format string (""). Finally, the graph produced by this grap 
program is the following: 



100 - 
50 - 

Millions of 20 — 
Telephones 
(log scale) 10 ~ 

5 - 

2 - 
1 - 




1900 '10 '20 '30 '40 '50 '60 '70 1980 



The number of telephones grew rapidly in the first decade of this cen- 
tury and then settled down to an exponential growth rate interrupted only 
by the Great Depression. A post-war growth spurt prompted a return to the 
pre-Depression curve. 

In the "grap Sampler/' which appears in the closing pages of this 
tutorial, you will see a variety of complex grap programs that also evolved 
from simple formats. 
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All the examples so far have placed data on the graph implicitly by 
copying a file of numbers (either a time series with one number per line 
pairs of numbers). It is also possible to draw points and lines explicitly. 
Here is a graph reflecting a specific placement of forms and text: 




20 40 60 80 



The grap instructions to draw on a graph are given in the following file: 
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.G1 

frame ht 2 vid 2 
cxx>rd X 0,100 y 0, 100 
grid dotted bot frcro 20 to 60 by 20 
grid dotted left f ran 20 to 80 by 20 
"Text above" above at 50,50 
"Text rjust " rjust at 50,50 
bullet at 80,90 
vtidc at 80,80 
box at (80,70) 
times at 80, 60 
circle at 50,50 
circle at 50,80 radius .25 
line dashed from 10,90 to 30,90 
arrow from 10,70 to 30,90 
draw A solid 
draw B dashed delta 
next A at 10,10 
next B at 10,20 
next A at 50,20 
next A at 90,10 
next B at 50,30 
next B at 90,30 
.G2 



The way of expressing the coordinate system (at n^, n) and the English- 
oriented instructions (above and rjust or dashed and dotted) make grap an 
intelligible language. 

The grid instruction is similar to the ticks instruction except that grid 
lines extend across the frame. The next two instructions plot text at 
specified positions. The markers (boxes, circles, times marks, and vticks) 
appear centered at their named coordinates. 

The circle instruction, for instance, draws a circle whose center is the 
place specified by at. The circle's size may be determined by stating the 
radius. The circle above is said to be .25 because grap understands all 
dimensions to be in inches though, like pic, you can scale your dimensions. 
If no radius is given, then the circle will be a default size: the small circle 
shown at the center of the graph. 
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The line and arrow instructions draw the obvious objects shown at the 
upper left. The plotting characters (such as bullet) are implemented as 
predefined macros, but more on that later. 

This example also illustrates the combined use of the draw and next 
instructions. Saying draw A solid defines the style for a connected 
sequence of line fragments to be cdlled A. Each subsequent instruction of 
next A at point adds point to the end of A. There are two such sequences 
active in the above example (A and B); notice that their next instructions 
are intermixed. Because the predefined string delta follows the specification 
of B, that string is plotted at each point in the sequence. 

grap has numeric variables (implemented as double-precision floating 
point numbers) and a familiar assortment of arithmetic operators and 
mathematical functions. 
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Macros 



grap provides the same rudimentary macro facility that pic does, 
sider the following grap file: 



Con- 



.G1 

frame ht 2 wid 2 
coord X 0,100 y 0,100 
grid dasher! bot f ran 20 to 80 20 
grid dashed left f rem 20 to 80 by 20 
define bsquare X "\ff*9\(sq\s-9" X 
define Isquare X "\s-1\(9q\sfr' X 
bsquare at 30,30 
Isquare at 70,70 
.G2 



Two macros, bsquare (big square) and Isquare (little square), are defined 
using the troff escape sequences, \(sq and \s. The big square is incremented 
three point sizes. And the little square is decremented one point size. They 
are then simply stated along with their respective locations. The graph 
looks like this: 



80 
60 
40 
20 
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Macros — — 

The method for defining macros is simple: 

define macro X replacement text X 

This definition stores the data from replacement text in the variable macro. 
Any character that does not appear in replacement text may be used as delim- 
iters for replacement text. Any subsequent occurrence of macro will be 
replaced by replacement text. (The bsquare and Isquare statements of replace- 
ment text are surrounded by double quotes because they are text, troff text 
in this case. As such they must conform to the grap rules for presenting 
text and take quotes.) 

The replacement text of a macro definition may contain occurrences of 
$1, $2, etc.; these will be replaced by the corresponding actual arguments 
when the macro is invoked. The invocation for a macro with arguments is 

name (argl, argl, ...) 

Non-existent arguments are replaced by null strings. 

The following grap program uses macros and arithmetic to plot crude 
approximations to the square and square root functions: 

(1. ^ 

fraite ht 1.5 wid 1.5 
define square X ($1)«($1) X 
define root I exp(log($1)/2) I 
define P % 

tmes at i, squared); i»i-i-1 

circle at j, root(j); j=j+5 

% 

i=1; j=1 
P: P: P; P; P 

J 

Because grap has the square root function sqrt, the macro root is valuable 
only for the purposes of demonstration. The delimiters used in the preced- 
ing example may not have been obvious. X and Y will be used as delimiters 
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Macros 



in most of the remaining examples. The preceding grap program produces 
25-" 




1 — I — r 

10 15 20 
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copy thru 



To plot files that are not stored as a time series or as x, y pairs, grap has 
a special mechanism. The copy instruction has a thru parameter that allows 
each line of a file to be treated as though it were a macro call, with the first 
field serving as the first argument, the second field serving as the second, 
and so forth. (Of course, using $1, $2, etc., the order of arguments can 
differ from the given sequence of columns: when given first, $2— 
representing the second column— would make column two equal to argu- 
ment one,) The thru instruction is the typical grap mechanism for plotting 
files that are not stored as time series or as x, y pairs. Its use will be illus- 
trated with the file, states.cp, which contains data on the fifty states: 



AK 


1 


401851 


WY 


1 


469557 


VT 


1 


511456 


DE 


1 


594338 


ND 


1 


652717 


CA 


45 


23667902 



The first field is the postal abbreviation of the state's name (Alaska, 
Wyoming, Vermont, ...), the second field is the number of Representatives 
to Congress from the state after the 1981 reapportionment, and the third 
field is the population of the state as measured in the 1980 Census. The 
states appear in increasing order of population. 

First, the graph will be given in population, representative pairs. (In 
the coord statement, log log is a synonym for log x log y.) 
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.G1 

label left "Representatives" "to Oongress" left .3 
label bot "Popilaticn (Millions)" 
ooord X .3,30 y .8,50 log log 
define PlotState X circle at ($3/1e6,$2) X 
oopy "states, cp" thru PlotState 
.62 



The copy instruction performs its usual task, reading in states.cp for its 
information. This time, however, the file was interpreted thru the defined 
macro, PlotState. The third column ($3) is divided by (/) one million 
(IxlO^ written in grap exponential notation as le6). Because $3 is given 
first, column three is the first argument for grap's coordinate system. The 
second column, $2, will be the second argument. Here is the finished pro- 
duct: 



Representatives 
to Congress 5 




1 10 
Population (Millions) 



Using circle as a plotting symbol displays overlapping points that are 
obscured when the data is plotted with bullets. The representation of a 
state is roughly proportional to its population, except in the very small 
states. 
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Multiple Coordinates 



The next plot will use the state's rank in population as the jc-coordinate 
and two different y-coordinates: population and number of representatives. 
Consequently, you would use two coord instructions to define the two coor- 
dinate systems pop and rep. You then explicitly give the coordinate system 
whenever you refer to a point, both in constructing axes and plotting data. 




frame ht 1.8 wid 2.3 

label left "Bopulation" "in Millions" "(Plotted as \(ba) 

label bot "Rank In Population" up .2 

label ric^ "Representatives" "(Plotted as \(sq)" 

ooccd pop X 0,51 y ,2,30 log y 

coord rep x 0,51 y ,3,100 log y 

ticks left out at pop ,3, 1, 3, 10, 30 

ticks bot out at pep 1, 50 

ticks ric^ out at rep 1, 3, 10, 30, 100 

thisranks50 

copy "states. cp" thru X 
bullet at pop thisrahk,$3/1e6 
square at rep thisrank,$2 
thisrank=thisrank- 1 




The copy statement in the program uses an "immediate macro" enclosed 
in Xs and thus avoids having to name a macro for this task, copying 
states.cp thru the lines between Xs is functionally identical to reading the 
file through a defined macro. Because the program assumes that the states 
are sorted in increasing order of population, it generates thisrank internally 
as a grap variable. The program produces the following graph: 
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Multiple Coordlnatos 



Population 
in Millions 
(Plotted as •) 




Representatives 
(Plotted as □) 



Rank In Population 



The plotting symbols were chosen for contrast in both shape and shad- 
ing. This graph also indicates that representation is proportional to popula- 
tion. Once you see this graph, though, you should realize that you don't 
really need two coordinate systems: you can relate the two by dividing the 
population of the U.S. — about 226,000,000 — by the number of representa- 
tives — 435 — to see that each representative should count as 520,000 peo- 
ple. If the purpose of this graph were to tell a story about American politics 
rather than to illustrate multiple coordinate systems, it would be redrawn 
with a single coordinate system. 
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for Loops and if Statements 



Many graphs plot both observed data and a function that (theoretically) 
describes the data. There are many ways to draw a function in grap: a 
series of next instructions is tedious but works, as does writing a simple 
program to write a data file that is subsequently read and plotted by the 
grap program. The for statement often provides a better solution. This 
grap program 



.G1 

fvaae ht 1 wid 3 
draw solid 
pi=atan2(0,-1) 
for i fron to 2»pi ty .1 do X next at i, sin(i) X 
.62 



produces 




The for statement uses the same syntax as the ticks statement, but the 
from instruction can be replaced by =, (which will look more familiar to 
programmers). It varies the index variable over the specified range, and for 
each value, executes all statements inside the delimiter characters, which 
use the same rules as macro delimiters. It is, of course, useful for many 
tasks beyond plotting functions. 

The if statement provides a simple mechanism for conditional execu- 
tion. If a file contains data on both cities and states (and lines describing 
states have "S" in the first field), it could be plotted by statements like 
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for Loops and if Statements 



if "$r "S" then X 

Plotstate($2,$3,$4) 
X else X 

PlotCity($2,$3,$4,$5,$6) 

X 

The else-clause is optional; delimiters use the same rules as macros and for 
statements. 
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grap Sampler 



.G1 

frame ht 4 wid 3.2 

label left •'Weis^it" "(Pounds)" left .3 
label bot "Gallons per Mile" 
ooord X 0,.10 y 0,5000 
ticks left in from to 5000 by 1000 
ticks bot in from to . 10 by .02 
copy "cars.qp" thru X circle at 1/$1, $2 X 
,.G2 



Excerpt from file carsxp: 

22 2930 

17 3350 

22 2640 
17 2830 

23 2070 

17 3170 
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grap Sampler 



5000 



4000 - 



3000 - 



Weight 
(Pounds) 



2000 - 



1000 - 




0.04 0.06 
Gallons per Mile 



0.08 



0.1 
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grap Sampler 





frame invis ht 4 vad 4 
ooord X 0,,10 y 0,5000 
copy "cars.cp" thru X 
tx=1/$1; tys=$2 
ballet at tx,ty 
tick bot at tx " " 



Excerpt from file cars.cp: 



tick left at ty " " 



X 





22 2930 

17 3350 

22 2640 
17 2830 

23 2070 



17 3170 
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grap Sampler 



I II nil iiiMiin nil 
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grap Sampler 





frame ht 4 \nd 3.2 
ODord X 38,85 y .8,10000 log y 
label bot "U.S. Amy Personnel" 
label left "Thousanas" left .3 
draw of solid # Officers Fenale 
draw ef dastiPd # Enlisted Female 
draw on dotted # Officers Male 
draw em solid # Enlisted Male 
copy "arny.cp" thru X 

next of at $1,$3 

next ef at $1,$5 

next om at $1,$2 

next em at $1,$4 

X 

copy thru % "$1 $2" size -3 at 60, $3 % xmtil "XXX" 
Ekilisted Hen 1200 
Male Officers 140 
Unlisted Wanen 12 
Female Officers 2.5 



XXX 




Contents of file ariny.cp: 



40 16.9 249 1 

42 190 12 2867 1 

43 521 36 6358 55 

44 692 47 7144 71 

45 772 62 7283 90 

46 240 16 1605 16 
50 63 4.4 512 6.5 
55 106 5.1 977 7.7 
60 86 4.2 761 8.2 
65 98 3.7 846 8.5 
70 138 5.2 1141 11 
75 85 4.5 640 37 
80 76 6.8 608 58 
83 80 9 606 67 
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grap Sampler 
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grap Sampler 





deldn $$ 

.EN 

.G1 

frame ht 3 vdd 4 

label left "Raric in" "Populaticn" 
label bot "Population (Millians)" 
label top "Slog sub 2$ (Pppulaticn)" 
oooKd X .3,30 y 0,51 log x 
define L % eiqp($Ulog(2) )/1e6 "$1" % 
ticks bot out at .5, 1, 2, 5, 10, 20 
tides left out fron 10 to 50 by 10 

tides tC9 out at L(19), L(20), L(21), L(22}, L(23), L(24) 
thisysSO 

oofRy "states. cp" thru X 

"$1" size -4 at ($3/1e6, thisy) 
thisy«thisy-1 

X 

line dotted from 15.3,1 to .515,50 
.G2 

.m 

delim off 





Excerpt from file states.cp: 



AK 
WY 
VT 
DE 
ND 



401851 
469557 
511456 
594338 
652717 



CA 



45 



23667902 
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log2 (Population) 
19 20 21 22 23 24 




0-5 1 2 5 10 20 

Population (Millions) 
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grap Sampler 



.G1 

frame iiwis ht .3 wid 4.5 botton solid 

lalsel bot "Kfnilations (in MilUons) of the 50 States" 

oootcl X .3,30 y 0, 1 log x 

Udcs bot out at .5, 1, 2, 5, 10, 20 

tides left off 

copy "states.cp" tfacu X vtidc at ($3/1e6,.5) X 
.G2 



Excerpt from file states.cp: 



AK 
WY 
VT 
DE 
ND 



401851 
469557 
511456 
594338 
652717 



CA 



45 



23667902 
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grap Sampler 



I I I I II II ID I I II I llllllll lllll III nil I II III I I I 



0.5 1 2 5 10 20 

Populations (in Millions) of the 50 States 
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frame invls ht 1 wid 4«5 bottom solid 

label bot "Populations (in Millioais) of the 50 States" 

ooord X .3,30 y 0,1000 log x 

ticks bot out at .5, 1, 2, 5, 10, 20 

tick left off 

oppy "states.cp" thru X "$1" size -4 at ($3/1e6, 100+rand(300) ) X 




Excerpt from file states.cp: 



AK 
WY 
VT 
DE 
ND 



401851 
469557 
511456 
594338 
652717 



CA 



45 



23667902 
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grap Sampler 



^ Krf>" SC WA GA NJ TX 
AK "T CO OH 

MT,„ ... ^ 



WY NM MS ^ NY 



VT SDNV 



IN 



HI M^Ajjc 
^ ME AL Wfr 

"1 \ \ \ 1 r 

0.5 1 2 5 10 20 

Populations (in Millions) of the 50 States 
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grap Sampler 




tides left off 

cury=0 

barht=.7 

oopyr "newengl.cp" thru X 
line frcm 0,cury to ($1/1e6,cuty) 
line from ($1/1e6,cury) to ($1/1e6,aiEy-baxht) 
line fran O.cury-bariit to ($1/1e6,cury-barht) 
" $2" ijust at 0,cury-barht/2 
curysscury-1, 

X 

line from 0,0 to 0,cury+1-barht 
barss-cury 

frame invis ht bars/3 wid 3 
label left "New Englani" "States" 

label bot "Population (in Millions)" , 

y 

Contents of file newengl.cp: 

511456 Vt. 
920610 N.H. 
947154 R.I. 
1124660Maine 
3107576Connecticut 
5737037Massachusetts 
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grap Sampler 



Vt. 



N.H. 



R.I. 



Maine 



Connecticut 



Massachusetts 



I I I 

2 4 6 

Population (in Millions) 
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New England 
States 



grap Sampler 




£rame ht 4 wid 3 solid 

label bot "ttopulatiaiis (in Millions) of the 50 States" 
label left "Mmtier" "of" "States'* 
tides bot out from to 25 5 
ooocd X 0,25 y 0,13 
OQiy "statepop.qp" thru X 

line frcm $1,0 to $1,$2 

line from $1,$2 to $1+1,52 

line frcm $1'i-1,$2 to $1+1,0 




Contents of file statepop.cp: 

12 

1 5 
27 
35 
47 
55 
60 
7 1 
80 
92 

10 1 

11 2 

12 

13 

14 1 

15 

16 

17 1 

18 

19 

20 

21 

22 

23 1 
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grap Sampler 




5 10 15 20 25 

Populations (in Millions) of the 50 States 
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grap Sampler 




frame invis ht 4 wid 4 bot solid left solid 

label bot "Populations (in HiUions) (tf the 50 States" 

label left "NUnter" "of" "States" left .2 

tides bot out from to 25 Icy 5 

ooozd X 0,25 y 0, 13 

ooiy "statepcp.cp" thru X 

line dotted ficm $1+.5,0 to $1-)'.5,$2 

"VCbu" size -3 at $1-i-.5,$2 




Contents of file statepop.cp: 

12 

1 5 
27 
35 
47 
55 
60 

7 1 

8 
92 

10 1 

11 2 

12 

13 

14 1 

15 

16 

17 1 

18 

19 

20 

21 
220 
23 1 
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grap Sampler 



10- 



Number 

of j 
States ': 

5- ! 



I 

5 



10 



15 



20 



25 



Populations (in Millions) of the 50 States 
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Introduction 



mv is a package of UNIX System V macros that format text for two types 
of transparencies (also called foils): viewgraphs (in a variety of dimensions), 
and 35 mm slides or 2x2 super-slides. The troffed output of the mv macros 
is not the transparency or slide itself, but the text on opaque paper that will 
later be used to make the transparency or slide. Because the text of the 
viewgraph is stored in a UNIX system file, and the output is on paper, you 
derive the additional benefit of being able to check the output, make 
changes, or correct errors, before you go to the time and expense of making 
the final transparency. 

The prerequisites to benefit from this tutorial are as follows: 

■ You should know what a file and directory are, and know 
how to create them. See the UNIX System V User Guide, 

■ You should know how to use a UNIX system text editor (ed, 
vi, and ex are examples). See the UNIX System V User Guide, 

■ You should be familiar with troff . See the tutorial in this 
book The Formatter troff: A Tutorial.** Also, the **nro£f /troff 
Technical Discussion*' in the Technical Discussion and Reference 
Manual discusses troff in detail. 

After reading this tutorial, you will be able to make transparencies in a 
variety of styles, in different fonts, and with oversize titles, and you will be 
able to use the reference material provided later in this chapter. (See the 
section titled "Reference Material.") 
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Some Examples 



The following two examples show you some of the macros that you can 
use to format text for transparencies with mv. As you look them over you 
will see that the macros in the mv package are much like other formatting 
macros you may have used: they are named with a one or two letter 
upper-case string, they begin on a new line, and the first character is always 
a dot (.). 

The macros shown in these examples are explained in greater detail in 
later sections of the tutorial. The output for these two examples, and for 
other examples used in this tutorial, is in the section "mv Sampler." 



Example 1: A Simple Transparency 

Suppose you have a file named steps.in, which contains the following 
lines: 



.vs 

Hie Friinaxy Steps in Pr^Brdx^ Documents 
.B 

Planniiig 
.B 

Writing 
.B 

Editing 
.B 

.TVpesetting 



.VS is one of several foil-start macros. (There are no foil-end macros.) 
Among other things, foil-start macros tell the typesetter what size the tran- 
sparency should be. Because it begins with .VS, this one will be 7x7 inches. 
.B, as we've seen, is a level macro; it specifies a level of indentation and a 
bullet (•) to mark the text that follows. 
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You can process the foil by typing one of the following command lines: 

mvt stepson | phototypesetter 
or 

troff -mv steps.in | phototypesetter 

Ask your system administrator which phototypesetter is appropriate to pro- 
cess your output. 



Example 2: A More Elaborate Transparency 

Suppose you wanted to make the transparency from Example 1 more 
elaborate: 



.vw 

Ihere are £our steps in prepa^^ngr docunezits 
.B 

Planning 
.0 

What documents exist? 
Can they be revised? 
.0 

Are new documents needed? 
.B 

Writing 
.B 

Editing 
.0 

By peers and su^^ervision 
.B 

Typesetting 

,C 

Using DCXWEMiEii's wfkeemch Software 



.Vw is another of the foil-start macros; it produces text that will fit on a 
7x5 inch transparency. .C specifies that another level be added beyond .B. 
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The Foil Start Macros (.VS, .Vw, .Vh, .VW, 
.VH, .Sw, .Sh, .SW, .SH) 



Every mv file must contain a foil-start macro. There are nine of them; 
each generates output for a different sized foiL 



Macro Name 


Size of Frame Opening 
and Type of Foil 


.VS 


7x7 inch viewgraph or 
2x2 inch super-slide 


.Vw 


7x5 inch viewgraph 


.Vh 


5x7 inch viewgraph 


.VW 


9x7 inch viewgraph 


.VH 


7x9 inch viewgraph 


.Sw 


7x5 inch 35-mm slide 


.Sh 


5x7 inch 35-mm slide 


.SW 


9x7 inch 35-mm slide 


.SH 


7x9 inch 35-mm slide 



NOOB 



Note that ,VW and .SW actually produce text for a 7x5.4 transparency 
(because typesetter paper is commonly less than 9 inches wide). The output 
from these two macros will have to be enlarged by a factor of 9/7 before 
they can be used to make 9x7 inch transparencies. 



The first character of a foil-start macro's name distinguishes between 
viewgraphs (V) and slides (S), and the second character specifies the dimen- 
sions of the foil. Varieties of sizes are as follows: 
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The Foil Start Macros 



S square 

w small and wide (7x5) 

h small and high (5x7) 

W big and wide (9x7) 

H big and high (7x9) 

By default each foil-start macro puts out three right-justified lines of 
identification information at the top of each foil. 

The current date in the form mo/dylyr 

AT&T 

FOILn 

where n is the sequence number in the current series of transparencies you 
are preparing. You can change the default heading information by using 
three optional arguments to the foil-start macro: 

.XX [n] [id] [date] 

where XX stands for one of the foil-start macros, n is the foil identifier (typ- 
ically a number), id is other identifying information, such as your initials or 
your company name, and date is the date. Example 6 shows the use of these 
options in an input file, and the "mv Sampler" shows the output for this 
example. 

Cross-hairs (+) mark the area of a transparency that will show through 
the opening of the cardboard frame to help you center the transparency in 
the frame. All foils other than the square (.VS) also have a set of horizontal 
or vertical crop marks that show how much of the transparency will be seen 
if it is made into a slide rather than into a viewgraph. 
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The Level Macros (A, .B, .D) 
Example 3: The Level Macros 

The text of this transparency explains mv's four levels of indentation. 
The "mv Sampler** shows the formatted output. 



6 USER'S GUIDE 



The Level Macros 



Vh 

.T "Foil Levels and Level Maries" 
.A 

This is the .A level. 
.B 

Ttiis is the .B level, 
.B 

and so is this; 
.C 

this is the .C level 
,C 

and so is this; 
.D 

and this is the .D level, 
,D 

and so is this. 
.A 

*rtiB large ballet, the dash, axvi the small ballet are the default "marlcs" 

for levels .B, .C, and .D respectively. 

However, you my arbitrarily nark these three levels: 

.B 2. 

like this (.B level); 
.C c. 

like this (.C level); 
.D ♦ 

like this ( .D level) ; 
•D iv, 

or like this ( .D level again). 
.A 

You cannot mark the .A level. 
.B 

You nay incluie as neny lines of text as you vdsh 1ji any item at any 
level; \f3troff\fP fills the text, but it does not adjust the margin or 
h/phenate words (as vdth this .B level item) . 



troff processes text after every level macro with line filling turned on. 
That is, the number of lines input do not necessarily match the number out- 
put. 
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The Level Macros 

Each of the foil-start macros automatically calls the .A level macro, that 

is 

.VW 

Hiere are four steps in preparing documents 

and 

•VW 
•A 

There are four steps in preparing docairaents 
give you the same results. 

•A precedes the line following it with a half-line of space. This blank 
half-line can be suppressed by giving an argument to .A. In fact any 
argument— any character or string of characters— will do. In the following 
example the character x is used as an argument to A (though it could have 
been N or 22 and still would have had the same effect): 

.A X 

Hiere are four steps in preparing documents 

Thus, the line following .A x will not be preceded by a blank half-line. 

The text that follows a .B macro is marked by a bullet, indented three 
spaces to the right, and is one-half a troff vertical space (one blank line) 
down from the preceding text. The mark that a .B macro produces can be 
changed, and the point size of the mark can be changed as well, by using 
the arguments shown below: 

.B [mark [size] ] 

•C level text indents farther to the right and also spaces one-half a troff 
vertical space (one blank line) down from the preceding text. The default 
mark it produces is a long (em) dash (— ). 

.C [mark [size] ] 

The text following a .D level-macro is marked by a small bullet, 
indented even farther to the right, and begins on a new line (but no blank 
line precedes the text of a .D macro. 

.D [mark [size] ] 
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Example 4: Repeated Level Marks 

If you call the same level-macro without any intervening text, you gen- 
erate a corresponding number of marks: 



.VH 

.T "Repeated Level Marks" 
.A 

Because the .A jsacro has no label » repeated .A macro calls are 

ignored. 

.A 

.A 

.A 

.A 

These are indentaticn level requests: 

.B 

.B 

.B 

Notice the mark. 

.D 

.D 

Notice the mark. 

.B 

.B 

Notice the mark. 

.B 

.A 

niis text is back to the left maoxrin. 



Look at the output of this example in the "mv Sampler" section to clarify 
this principle. 
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Titles CT) 

Example 4 also shows how to use .T to create a centered title for your 



foil: 



.VH 

•T "Repeated Level Msorks" 



On output, the size of the text that is the argument to a .T macro is four 
points larger than the prevailing point size. You must enclose the argu- 
ment to .T in double quotes if it contains blank spaces. 



Point Sizes and Line Lengths (.S) 

To change the point size of your text, use the .S macro. 



.A 

This text is at the prevailingr point size. 

.S 10 

.A 

Ttds text is at 10 point. 



If you give .S a null first argument (that is, .S you restore the previous 
point size. 
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.A 

The text is at the prevailing point size. 

.S 10 

.A 

This text is at 10 point. 
.S 
I -A 

\This text is bade at the prevailing point size. 



A negative argument to ,8 (for example, -2), reduces the default point size 
by the amount specified. If the argument is positive (+2), it is added to the 
default, and if there is a null argument, as above, it becomes the new point 
size. 

Change your foil's line length by giving .S a second argument, which 
becomes the prevailing length. You may specify the line length in any 
metric that you choose (ems, inches, and so on). If you do not specify the 
metric of this second argument and it is less than 10, troff interprets it as 
inches; if the second argument is greater than 10, it is taken as troff units 
(see the "nroff /troff Technical Discussion" in the Technical Discussion and 
Reference Manual). 




Global Indents (J) 

Shift the entire text (except titles) of the foil right or left with the J 
macro: 

,1 +10 a X 

The first argument specifies the amount of indentation mv will use to estab- 
lish a new left margin. This argument may be signed positive or negative, 
indicating right or left movement from the current left margin. If 
unsigned, the argument specifies a new margin, relative to the initial 
default margin. If you do not specify units, mv assumes that you mean 
inches (see the "nroff /troff Technical Discussion" in the Technical Discussion 
and Reference Manual for legal troff formatter units). If the argument is null 
or omitted, mv assumes Oi (zero inches), causing troff to revert to the initial 
default margin. 
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If you specify a second argmnent •! calls the .A macro before exiting. 
The third argument, if you use it, is passed to the .A macro to suppress vert- 
ical spacing. Example 5 illustrates this point. 



Changing Fonts (.DF) 

Helvetica Regular, mounted in position 1 on your typesetter, is the 
default font for viewgraphs and slides formatted with mv. You can mount 
additional fonts and change the default font with the .DF macro. The argu- 
ments to the .DF macro in the following example load roman font in posi- 
tion 1 (so that it becomes default), italic in position 2, bold in position 3, 
and Helvetica in position 4: 

.DF 1 R 2 I 3 B 4 H 

After you enter this line in your file, using the escape sequence for chang- 
ing fonts (\£n) loads the fonts you specified for each position. 

.B 

\f 1roroan\f2italic\f 3bold\f 4lfelvetioa 

If you use .DF, you must use it immediately before a foil-start macro. 

Using the following arguments to the .DF macro is equivalent to using 
mv's default loading of fonts: 

.DF 1 H 2 I 3 B 4 S 



Changing Vertical Spacing (.DV) 

Change the default vertical spacing of the four level macros with .DV. 
mv calculates vertical spacing in troff vertical units (v). This control line 
changes the spacing for the .A level to .7v, spacing for the .B level to .4v, 
and the spacing for the .C level to 0. 

.DV .7v .4v Ov 

The default setting is equivalent to the setting shown in this line: 
.D7 .5v .5v .5v Ov 
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Underlining (*U) 

To underline a line of text, precede it with the .U macro, like this: 

,U "DOCUMENrER's WORKBENCH Software" 

The .U macro takes one or two arguments. The first argument is the string 
to be underlined, the second, if you include it, is not underlined but con- 
catenated to the first argument. 

Synonyms 

In general, you should not intermix troff formatter requests arbitrarily 
with the mv macros, because this often leads to undesirable (and sometimes 
surprising) results. The mv package recognizes the following upper-case 
text synonyms for the corresponding lower-case troff requests. 



Synonym 


Meaning 


•AD 


turn on line adjustment 


.BR 


line break 


.CE 


center the line 


.FI 


turn on line filling 


.HY 


turn on hyphenation 


.NA 


turn off hyphenation 


-NF 


turn off line filling 


.NH 


turn off hyphenation 


.NX 


next file 


.SO 


switch source file 


.SP 


space 


.TA 


set tab stops 


.TI 


temporary indent 



troff requests that are safe to use correspond to these upper-case 
synonyms. The "nroff /troff Technical Discussion" in the Technical Discussion 
and Reference Manual explains in detail how the lower-case equivalents to 
these upper-case synonyms work. 
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You should use other troff formatter requests sparingly (if at all). Be 
particularly careful when using requests that affect point size, indentation, 
page offset, line and title lengths, and vertical spacing between lines. In 
cases such as these, use the .1 and .S macros instead, because they do more 
work for you. For example, the .S macro changes point size and adjusts vert- 
ical spacing appropriately. 



Line Breaks 

The .S, .DF, .DV, and •U macros do not cause a line break. The J macro 
causes a break only if you call it with more than one argument. All other 
mv macros always cause a break. The troff synonyms .AD, .BR, .CE, .FI, 
.NA, .NF, .SP, and .TI also cause a break. 
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Line Filling, Adjusting, and Hyphenation 

By default the mv macros turn on line filling, but they neither adjust 
nor hyphenate lines. These defaults can, of course, be changed by using the 
troff synonyms for filling, adjusting and hyphenation. 



Example 5: A Complicated Transparency 

The following input combines a variety of mv features, specifying a 
title, changing point size and fonts, and using some of the troff synonyms. 
The output of this example is in the "mv Sampler" section. 




.VS 5 Oonplex 

.T "Of Bits & Bytes & Vtords" 
.8 -4 
.1 3 A X 
.ft I 

But let your cxxnunication be, Yea, yea; 
Nay, nay: for vAiatsoever is more than these 
ocmeth of evxl.« 
.ft 

.1 a nospace 
Matthew 5:37 
.ER 
.3 

.1 
.A 

Binary notation has been arxxoxl for a 

.S +6 

long 

.S 

time. 
.B 

ThB above verse tells us to use: 

J 
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Line Filling, Adjusting, and Hyphonation 
Example 5 continued: 



Binazy notation, 

.ft I 

and 

.ft 

.C 2) 

Redundancy 
.D Mrh 

(in oG(miuxu.cating) 
.B 

Binary notaticsi is 
.U nDt 

suitied for hiroan use, contrary 
to what the verse above suggests. 
.SP 
.S -4 

.U 

.BR 

♦ TSie use of this verse in the context 
of binary notation is plagiarized 
frcm C. Shannon. 
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Using the Preprocessors with mv 



You can use various preprocessors to typeset information that requires 
more powerful formatting capabilities. 

Use tbl to set up columns of data within a viewgraph or slide. The .TS 
and .TE macros are not defined in the mv macro package, but are merely 
flags to tbl. You can learn about tbl by reading "The Preprocessor tbl" in 
this User's Guide. You can find details about tbl in the "tbl Technical Dis- 
cussion" in the Technical Discussion and Reference Manual. 

Use the eqn preprocessor to typeset mathematical expressions and for- 
mulas on transparencies. The chapter "The Preprocessor eqn" in this guide 
provides details about using this preprocessor. .EQ and .EN are flags to 
eqn, and are not defined in the mv macro package. 

You can also use the pic and grap preprocessors with mv. This guide 
provides tutorials on both of them. Their delimiters are flags to their pro- 
grams, and are not defined in the mv macro package. 

Example 6: A Transparency with Tables and an 
Equation 

Here is an example of a foil containing an equation and a table: 
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Using the Preprocessors with mv 



.VS 6 "T5ifi Wbrte: Output" 
.BQ 

delim $$ 
gsize 14 
.EN 

.10 a 

.SP 

.TS 

center doublebcx ; 
Cipf4 I Cip+4 S S 
i L L L 

"Icicle 
'^Icicle 

Li I C I C I M . 
U^er ' s<nfi^Har(iMare 

<1»B> <1»B^ <TiS> 

<nm>CND^* (lbKMB^Model<nB>Serial 
<iuffi>SystaiKws>\'^<SAB»>NksEber 

OS Dev.<i»B>A<»ffi>VAX<i3AE^54 
SGS Dev.<MB>B<iMB>11/70<^ts>3275 
LGW-End<nua>C<»B> 1 1/23<wb>221 

And . . .<oua>T{ 

Seme tesct and an Gquaticn: 
T}<»B>T{ 

$ zeta (s) = prod fran Ic=1 to inf k svq> -s $ 
*AD 

T}<M>1.2 

.sp 

.TE 

delim off 
gsize 10 
•EN 
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Using Constant Width Font 

Your phototypesetter may have a constant width font available. Use the 
.DF macro to define the font position. For example: 

•DF 1 R 2 I 3 OW 

Then, define the .CW and .CN macros to include the font change, like 
this: 
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Phototypesetter Output 

Obtain typeset output with the mvt command. 

mvt [ options ] [ /t/e 1 1 phototypesetter 

The file argument names a file that contains the text (and macros) to be 
typeset. The options argument can be one or more of the following: 



—a previews output on a terminal (other than a TEK- 

TRONIX 4014) 

-e calls eqn 

-t calls tbl 

— p calls pic 

-g calls grap 

-Ittyjype formats output for ttyjype, where ttyjype refers 
to a phototypesetter. mv supports the ttyjype 
value 4014 (TEKTRONIX 4014). 

-Ddest directs output to device dest, mv supports the 

dest value 4014 (TEKTRONIX 4014). 

-z directs output to the standard output. 



If you use a hyphen (-) in place of file, mvt reads the standard input 
(rather than a file). 

The phototypesetter argument is the device name of a printer or terminal 
capable of producing phototypeset output. Your system administrator 
should know what name is appropriate. 
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Output Approximation on a Terminal 



You can obtain an approximation of the typeset output with the mvt 
option —a. 

mvt -a [file 

Use this option to preview the formatted text on a VDT screen or on a 
typewriter-hke printer. It approximates the final output except that: 

■ You cannot see point-size changes. 

■ You cannot see font changes. 

■ Titles that are too long appear proper. 

■ All horizontal motions are reduced to one horizontal space to 
the right. 

■ All vertical motions are reduced to one vertical space down. 

For example, it will appear that lines of text following a .B, .C, or .D macro 
are not aligned properly (even though they will be in the typeset output). 

Although you cannot determine alignment from this approximation, 
you can observe line breaks and the amount of vertical space required by 
the text. If the foil is not full, the macro package prints the number of 
blank lines (in the current point size) that remain on the foil; if the foil is 
full, mv prints a warning. If the text overflows the foil, mv prints the text 
after the cross hairs. 



Names Reserved by mv 

The mv macro package uses certain names internally. All 2-character 
names starting with either or are reserved. Experienced users of the 
UNIX system or the mv macro package may want to define strings, or write 
additional macros. You cannot use names that are the same as those of the 
mv macros, strings that are described in this section of the tutorial, or 
names that are the same as troff names. Furthermore, if you use any of the 
preprocessors, you also must avoid their reserved names. 
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Miscellaneous Information 

The .S macro changes the point size and vertical spacing immediately, 
but a line-length change requested with that macro does not take effect 
until the next level-macro call. Specifying a third argument to the .S macro 
usually results in a disaster. 

The \*(Tm string generates a trademark symbol. 

The tilde (*) is interpreted by the mv macros as an unpaddable space; 
that is, the tilde may be used wherever you desire a fixed-size (non adju- 
stable) space. To override this condition, the following line should be 
included in the input file: 

.tr " 
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Dimensional Details 



For each size of viewgraph, the following table shows the default point 
size, the maximum number of lines of text (at the default point size), and 
the height, width, and aspect ratio, both nominal and actual. 



Maximum 
Macro Point Lines 
(Note 1) Size (Note 2) 


Nominal 


Actual (TEXT) 


^ " 1/AR 
-(Note 3)- ^^^^ 


^ ^ 1/AR 
-(Note 3)- 


.VS 18 21 


7 7 1 1 


6 6.8 1.13 .88 


.Vw 14 19 
.Vh 14 27 
.VW 14 21 
.VH 18 28 


7 5 .71 1.4 
5 7 1.4 .71 
7 5.4 .77 1.3 
7 9 1.3 .77 


6 4.8 .8 1.25 
4.2 6.8 1.6 .62 
6 5.2 .87 1.15 
6 8.8 1.5 .68 


.Sw 14 18 
.Sh 14 27 
.SW 14 18 
.SH 18 28 


7 4.6 .67 1.5 
4.6 7 1.5 .67 
7 4.6 .67 1.5 
6 9 1.5 .67 


6 4.4 .73 1.4 
3.8 6.8 1.8 .56 
6 4.4 .73 1.4 
5 8.8 1.76 .57 



NOflE 



If used as viewgraphs, the .SW macro and .VW macro generated foils must 
be enlarged by a factor of 9/7. 

Maximum number of lines of text at the default point size. 
W-Width in inches, H-Height in inches, AR-Aspect Ratio (H/W). 



The Production of Viewgraphs and Slides 

The phototypesetter produces output on mechanical paper, which is 
white, opaque, photographic paper. There are several simple processes (for 
example, Thermofax, Bruning) for making transparencies from opaque 
paper. Because some of these processes involve heat, and because mechani- 
cal paper is heat sensitive, you should first make copies of the photo- 
typesetter output on a good-quality office copier, and then use these copies 
for making your transparencies. 
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Making slides is a more complicated photographic process than making 
viewgraphs. It is possible to make both positive (opaque letters on tran- 
sparent background) and negative (transparent letters on opaque back- 
ground) slides, as well as colored-background slides, etc. It is probably best 
to consult a professional in cases like these. 



General Guidelines for Using mv 

■ The most useful foil sizes are .VS and .Vw (or .Sw). This is 
because most projection screens are either square or wider than 
they are tall, and also because the resulting foils are smaller, 
easier to carry, and require no enlargement before use. 

■ You should avoid reducing point size below the default value. 
Default point size for each type of foil (Table 3) is the smallest 
point size that produces a foil that is legible by an audience of 
more than a dozen people. If there is more text than will com- 
fortably fit on one foil, you should use two or more foils instead 
of reducfng the point size. 

■ You should avoid numerous font changes. A foil with more 
than twp typefaces looks cluttered and distracts the viewer. 

■ You should avoid underlined typeset text. Even though this 
package contains a macro for underlining, you probably should 
not use it. Underlined typeset text almost always looks bad; 
instead, use a different typeface. 

■ The Helvetica sans-serif font is thicker and easier to read than 
the Times Roman serif font normally used for typesetting. On 
the other hand, the Times Roman font permits more text to be 
squeezed onto a foil. If you intend to use italic and /or bold 
typefaces, either the Helvetica regular, italic, and medium 
(which is actually a bold typeface): 
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.DF 1 H 1 HI 3 HH 
or the Times Roman regular, italic, and bold: 
.DF 1 R 2 I 3 B 

should be mounted via the .DF macro. Bold typefaces tend to be 
a bit overwhelming. Choice of fonts is primarily a matter of 
personal choice. 

■ You can use the .SP macro to insert a bit of additional white 
space (for instance, .5v or Iv) at the top of each foil (that is, 
increase the top margin). 

■ Normal upper-case and lower-case text is more legible than 
upper-case text only. (In smaller point sizes, however, lower- 
case characters may be hard to read.) Upper-case and lower-case 
alphabets have evolved because they result in more legible text. 
Furthermore, such text is less bulky than upper-case text only, so 
you can put more information onto a foil without crowding. 

■ You should make foils for a presentation as consistent as possi- 
ble. Changing fonts, typefaces, point sizes, etc., from foil to foil 
tends to distract the viewer. While it is possible to emphasize 
and draw the viewer's attention to particular items with such 
changes, this works only if it is done purposefully and spar- 
ingly. Overuse of these techniques is almost always counter- 
productive. 

In summary, the dictum that "the medium is the message** does not 
apply to foil making. When in doubt: 

■ Do not change point sizes. 

■ Do not change fonts or typefaces. 

■ Do not underline. 

■ Use many sparse foils rather than a few dense ones. 

■ Use fewer words rather than more words. 

■ Use larger point sizes rather than smaller point sizes. 
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■ Use larger top and bottom margins rather than smaller ones. 

■ Use normal upper-case and lower-case text rather than 
upper-case text only. 
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The mv Sampler 

This Sampler contains the formatted output of the examples shown in 
this tutorial. The output has been reduced in order to fit the page size of 
this guide. 
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The mv Sampler — 

The Primary Steps in Preparing Documents 

• Planning 

• Writing 

• Editing 

• Typesetting 



Example 1: A Simple Transparency 
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There are four steps in preparing documents 

• Planning 

— What documents exist? Can they be revised? 

— Are new documents needed? 

• Writing 

• Editing 

— By peers and supervision 

• Typesetting 

— Using UNIX DOCUMENTER'S WORKBENCH Software 



Example 2: A More Elaborate Transparency 



THE MACRO PACKAGE mv 29 



mv Sampler 



Foil Levels and Level Marks 

This is the .A level. 

• This is the .B level, 

• and so is this; 

— this is the .C level 

— and so is this; 

• and this Is the .D level, 
. and so Is this. 

The large bullet, the dash, and the small 
bullet are the default "marks" for levels .B, .C 
and .D respectively. However, you may 
arbitrarily mark these three levels: 

2. like this (.B level); 

c. like this (.C level); 
* like this (.D level); 
Iv. or like this (.D level again). 

You cannot mark the .A level. 

• You may Include as many lines of text as 
you wish in any item at any level; troff will 
fill the text, but it will not adjust or 
hyphenate it (as with this .B level item). 



Example 3: The Level Macros 
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The mv Sampler 

Repeated Level Marks 

Because the .A macro has no label, repeated 
macro calls are ignored. 

These are indentation level requests: 

• 

• Notice the mark. 

. Notice the mark. 

• Notice the mark. 

This text is back to the left margin. 



Example 4: Repeated Level Marks 
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Of Bits & Bytes & Words 

But let your communication be. 
Yea, yea; Nay. nay: for 
whatsoever is more than these 
Cometh of evil* 

Matthew 5:37 

Binary notation has been around for a long time. 

• The above verse tells us to use: 

1) Binary notation, and 

2) Redundancy 

(in communicating) 

• Biliary notation is not suited for human use, 
contrary to what the verse above suggests. 



* The use of this verse in the context of binary notation is 
plagiarized from C. Shannon. 



Example 5: A Complicated Transparency 
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Users 


Hardware 


UNIX™ 
System 


Model 


Serial 
Number 


OS Dev, 
SGS Dev. 
Low-End 


A 

A 

B 

C 


VAX 

11/70 
11/23 


o4 
3276 
221 


And now ... 


Some text 
and an 
equation: 


Jfc=i 


1.2 



Example 6: A Transparency with Tables and an Equation 
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offset ... 14 
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slides ... 1, 4-5, 12, 17, 23-24 
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underlining ... 13, 24 
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Introduction 



This tutorial is intended to give you a working knowledge of checkmm, 
diffmk, hyphen, ndx, ptx, and subj. When you have prepared a document 
draft, hyphen will help you to proofread it. checkmm will check your 
macro usage for possible errors, diffmk will make later revisions of your 
work more manageable. When you are satisfied that you have produced a 
polished document, subj, ndx, and ptx will help you to make an index. 

You should be familiar with the following concepts and tools to fully 
benefit from this tutorial. 

■ You should know how to use a UNIX System V text editor 
(ed, vi, and ex are examples). See the UNIX System V User 
Guide. 

■ You should know what a file and directory are and know 
how to manipulate them. See the UNIX System V User Guide. 

■ You should know how to redirect input and output using 
pipes. See the UNIX System V User Guide. 

■ You should be familiar with a UNIX System V formatter 
(nroff or troff ). See the tutorials in this book that discuss 
nroff or troff. 

■ You should be familiar with the mm macro package in order 
to understand the explanation of checkmm. See the tutorial 
in this book that discusses mm. 
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Checking your File 

This section shows you how to check your file before it is formatted or 
sent to a printer. The tools discussed here will help you catch formatting 
errors before you print, saving time, paper, and computing resources. 

Using checkmm 

checkmm examines your file to identify potential mm usage errors. For 
example, if you used .DS to start a display but forgot to close the display 
with .DE, checkmm will find the mistake. If you prepared a formal 
memorandum and began it with inappropriate requests or macros, 
checkmm will complain. 

checkmm is easy to use: you simply type 

checkmm my.file 

and errors (providing you have any) will come up on your screen. If you'd 
like a more permanent record of these errors, type 

checkmm my.file > errors 

and read the contents of the file, errors, for checkmm's error messages. 

If you have no errors checkmm will tell you so. For instance, if you 
had typed 165 lines into the file draftl you could check it for mm- 
correctness as follows. Assuming there were no mm errors, typing 

checkmm draftl 

would cause the following message to print across your screen: 
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Checking your file 



r 




drafti: 



165 lines dcsne. 



$ 





That is, "No errors." 

But if you had forgotten to close a display with a .DE macro, you might 
have gotten the following message: 




drafti 



.D6 at line 54 within .D6 
165 lines doone. 

$ 



In this case, checkmm read drafti, saw two .DS macros and no intervening 
.DE macro, and complained that you were trying to put a display inside a 
display (an illegal action in mm). In other words, it saw that you had for- 
gotten to end the first display. 

This example suggests that checkmm is inclined to give you the benefit 
of the doubt. It will take note of a possible error, but only when it has pro- 
cessed to the point where something must be wrong will it complain. 
Another example of this is its handling of formal memoranda macros. 

Here are the macros you would use to begin a memo: 
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.ND "date"" 

•TL case number 

Document title 

.AU "Author's name" and additional information, 
.AT "Author's title" 
.MP *^Memo type" 



checkmm will accept the absence of unessential macros like .ND and .AT, 
or it will allow you to intersperse other requests, such as those for adjusting 
line length or indent, for centering text, and so on. But it will complain if 
you enter any of these macros out of the order shown above. Had you, for 
example, entered the .ND macro after the TL in a file called memol, then 
typing 



checkmm memol 

would produce these results: 



menol: 

Beginnin? macaco sequence e r ror before ,m at line 6 




checkmm reads through to the .MT macro before deciding you've commit- 
ted an error; you must search upward in the file from this point to find 
what caused the actual error. 
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nroff and tro£f provide you with a fine level of control over hyphena- 
tion. You can make precise decisions about the way words break across the 
boundary from the end of one line to the beginning of the next. As the 
"nro£f/tro£f Technical Discussion** shows you (see the Technical Discussion and 
Reference Manual), you can turn on automatic hyphenation with the request 
.hy, you can turn off all hyphenation with the request .nh, and/or you can 
specify a selective version of automatic hyphenation with .hw. After your 
document is formatted, you might like to go back and see the results, that 
is, see all hyphenated words with the hyphen command. 

hyphen is straightforward. You simply type 

hyphen out.file 

and you get a list of all words that have been hyphenated in the file you 
named on the command line. (Don't forget that only formatted files reflect 
nroff's or troff's automatic hyphenation.) 

Here is another way to check your file for hyphenation: 

mm -Tip -rW72 memol | hyphen > memol.hy 

This command line formats the file and pipes the output (in this case, a file 
processed by nroff and mm, prepared for printing on the line printer, and 
specified to have lines of 72 characters) through hyphen. The results are 
sent to a file called memol.hy. This last file doesn't contain the formatted 
document; it contains all words in that document that were hyphenated 
across a line break. To inspect the hyphenations that will appear in the 
document, you must give hyphen the same formatted file that you will send 
to the printer. Different formats — longer lines or fewer lines, for 
example— will result in different hyphenated words, hyphen ignores 
hyphenated numbers, such as phone numbers. 
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diffmk is a valuable tool for comparing successive versions of a docu- 
ment. It allows you to see two things at once: the most up-to-date version 
of a document, and those lines that are different from the previous version. 

When you are revising a document it is good practice to copy the origi- 
nal and edit the copy. Once these alterations are complete, you can see 
your changes against the background of the original with diffmk. By typ- 
ing 

diffmk originaLfile revised.file diffmk.file 

you form diff mk«file, based on the differences from originaLfile and 
revised.file. Note that the first two files are not changed as a consequence 
of diff mk's analysis. 

When you format this diffmk'd version, using nroff or troff, a vertical 
bar in the margin will identify those lines you have revised. An asterisk in 
the margin will indicate places where lines of text have been removed. An 
unformatted version of di£fmk.file is identical to revised.file with the addi- 
tion of .mc (margin character) requests. 
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Making Indices witii subj, ndx, ptx, and mptx 



Replacing the tedious and error-prone manual task of making an index, 
DOCUMENTER'S WORKBENCH Software provides the tools, subj and ndx, for 
generating indices automatically. They are easy to use and are compatible 
with the DOCUMENTER'S WORKBENCH formatters and macro packages, subj 
analyzes your text for words that appear to be subjects, and ndx produces an 
index of those words and the page numbers on which they appear. 

To use these tools, you should know how to use a UNIX text editor, and 
you should be familiar with DOCUMENTER'S WORKBENCH Software com- 
mand lines. (See the table at the conclusion of the User's Guide "Preface.") 



Tiie Subject-List Malcer: subj 

subj decides which words in your file are keywords: the ones that sug- 
gest what your file is about. It looks for capitalized words, assuming they 
are proper nouns, and for modifier-noun sequences. It also pays special 
attention to the words you use in abstracts, headings, introductory para- 
graphs, and the topic sentence of each paragraph. 

subj remembers these ke)rtvords and examines your document in incre- 
ments of two-sentence sections (first and second, second and third, and so 
forth) attempting to tie relevant keywords together. In this way function 
words and phrases, such as prepositional phrases, don't isolate potential 
subjects and subject-modifiers from each other. 

Perhaps you can see already that subj has its own expectations of your 
writing. It assumes that each sentence begins on a new line, so it can disre- 
gard capitalized words that begin sentences. It assumes that you will 
present your text in neat and relevant blocks of information, and that these 
blocks will have headings or subheadings. Finally, it expects you to observe 
the classic thesis essay form: thesis sentence or sentences at the beginning 
of the text and a topic sentence at the start of each paragraph. Should you 
go off on a tangent or include an irrelevant name, you might have a 
subject-list that better reflects a document's problems of exposition than its 
real purpose or thesis. Normally you would want to edit a subject-list 
before using it, but first let's see how to produce one. 
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The command line you would type to use subj is the following: 
subj my.file 

Supposing you wanted a subject-list of this section of the tutorial (stored in 
a file named tutorial), you would type 

subj tutorial 

which would produce the following output: 
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ocznrtand line 
oamand lines 
document 
docunenter 

DOOMENTESl'S WCStKBENCH 

editor 

error-prciie 

examines 

file 

file named tutorial 

follcwing 

generating indices 

Guide wards writing 

increnients 

index 

keywords 

iiaking 

neddng iiKdces, subj ndx ptx 

mptx making indices 

nfbc 

ones 

own esqpectations 
Preface 

relevant keywords 

replacing 

second 

subj 

subj sopposiijg tables tools tutorial unix 

subject-list 

subject-list naker, subj 

supposing 

task 

third 

tools 

tutorial 

two-sentence sections 
unix 

User's Guide 

words 

writing 
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Notice that it recorded both headings in full and that it focused on the 
opening sentence, mentioning the mm tutorial. Had mm been mentioned 
down in the middle of a paragraph, it would have been ignored. Thus, 
presenting unimportant information in the opening paragraph of an essay 
or report will be given disproportionate importance in the subject-list. (In 
fact, this list suggests that the file contains information about mm. But 
although the file mentions mm, it is not the topic of the file, and might be 
deleted from the final list.) 

subj works especially well with files that contain requests and macros. 
Knowing how these formatting commands are normally used, subj takes 
cues from text prepared with DOCUMENTER'S WORKBENCH Software that 
conventional text cannot offer. This does not compromise the other criteria 
subj uses to choose subjects, but rather complements them. While a 
subject-list might be valuable in a variety of ways, making indices is prob- 
ably its most useful function. 



Indexing Documents with ndx 

The DOCUMENTER'S WORKBENCH Software index maker, ndx, reads the 
subject-list file, compares the words in it to the text, and records the subjects 
it finds and their corresponding page numbers. Because ndx focuses on the 
roots of words it finds in the subject-list, tenses and cases of words pose no 
problems to it. The following is an example of ndx at work. Notice that it 
uses a subject file, which you can make with subj: 

ndx subject.£ile "mm -Tip -rW72 my.file" > index.file 

subject.file must contain a list of subjects drawn from the text or book 
you're indexing. You can use subj to make this list or you can select 
another method. It makes no difference to ndx. Next you give the com- 
mand line you would use to generate the document you're indexing. 
Enclose it in double quotes. A few things should be said about using ndx: 

■ You are not actually sending anything to a printer, ndx makes a 
copy of the document, which you never see, then removes it. 

■ Be sure to give the same command line to ndx that you use 
when you format your document, ndx needs this information to 
make decisions about page numbers. A command line given to 
ndx that differs from the command line used to print the docu- 
ment will probably produce an inaccurate index. 
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■ ndx will accept any DOCUMENTER'S WORKBENCH Software for- 
matter with or without the mm macro package. The formatting 
command line must be enclosed in double quotes. 

■ ndx will not accept command line operators such as |, >, <, and 
&. Consequently, command lines that use preprocessors (e.g., 
grap, pic, tbl, and eqn) are disallowed on the ndx command 
line. 

Should you need to index files that use one or more preprocessors, run the 
appropriate preprocessor before indexing and formatting: 

grap my.file | pic | tbl | eqn > preprocessed.file 
Then give the preprocessed file to ndx: 

ndx subject.file "troff -mm preprocessed.file" > index.£ile 
Last, make sure you use the same preprocessed file when printing: 

troff -mm preprocessed.file | typesetter 

The file, index.file, contains the finished index complete with alphabetical 
topic entries and corresponding page numbers. 

Because ndx is intelligent enough to identify word-roots, you may find 
that it is too permissive in certain cases. To ensure that ndx literally 
matches a particular entry in your subject-list, begin the line on which the 
entry appears with a tilde ("): 

^hyphenation 
^revision 

"preprocessing files 

ndx will find only precise matches for these words. The tilde will not, 
however, identify phrases to be literally matched. 

Given the brief subject list above, ndx would find "selection of 
hyphenated words" to be a miss but would identify "hyphenation" as a hit. 
You'll notice in the last example that each word following the tilde is desig- 
nated as a literal entry. Thus, "preprocessed files" would not be matched, 
but "files that need preprocessing" would be. ndx has no provision for 
selectively isolating single words on a line. Either each word on the line is 
treated as a literal entry or none of them are. 
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Making Permuted Indices with ptx, mptx, and subj 



Besides the subject/page-number index made with ndx, DOCUMENTER'S 
WORKBENCH Software has commands to make another type of index: the 
permuted index, made with ptx and mptx. Like a concordance, a permuted 
index is a catalog of keywords taken in their immediate contexts. The index 
is called "permuted" because it changes the word order, placing the keyword 
in the middle of the line. Index lines are presented alphabetically by key- 
word. 

ptx, together with its eight options, reads the file you wish to index, 
selects keywords and contextual words, and prepares a file that will be pro- 
cessed to make the final index, mptx is a specialized macro package that 
interprets the file that ptx prepares. 

The simplest statement of ptx use is as follows: 
ptx my .file index.file 

This gives ptx, respectively, the file you want it to read and the name of a 
file it can put its output in. Next, you simply give the output from ptx to 
the mptx macro package and an appropriate formatter to print your per- 
muted index: 

mm -mptx index.file > permuted.index 

An appropriate formatter is one that will process whatever headings, titles, 
or other features you want to include with your permuted index. 
Remember, your permuted index is made from a formatted document. In 
the preceding case, the index was processed with mptx and mm (which 
invoked nroff). 

ptx's default selection of keywords is generous, and the index produced 
by the above examples would probably be too large to be useful. You will 
probably want to give ptx a limited subject-list before it begins its work. 
You might, therefore, want to begin your session of indexing by using subj. 
(See the section of this tutorial that discusses subj.) 
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Assuming you wanted to make a permuted index of this section of the 
tutorial, you would proceed as follows. First, you would make a subject-list: 

subj tutorial > subj.file 

An edited version of the file, sub)\file, is shown in the following figure. 



ei^ optioRs 
index iispat 
input 

isolates contextual words 
keywords 

maldiig perttuted indices 

ptx 
subj 

jBub ject/page-nmber incbex 



Then, you would use ptx with its -o option: 

ptx -o subj.file tutorial tutandex 

The -o option signifies "only," and is followed by an "only file." That is, 
only the words in the file following — o will be used by ptx as ke)rwords. 
The file, tutorial, here is a formatted file. Once ptx has been given a 
subject-list, it expects to receive a formatted file, so it can get down to the 
business of extracting all ke)rwords, including those in defined strings and 
defined macros. 
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Finally, you would process the file, tutindex, to produce the permuted 
index itself. 

mm -mptx tut.index > permuted.index 

The following is the contents of the file, permuted.index. 



alphabetically by keyword, 
selects keywords and isolates 
wish , together with its 
package dedicated to pemuted 
of the file that will oontain the 
Like a canoordanoe, the pemuted 
their imooediate contexts. 1336 
the pemuted 
Besides the subject/page-nucDber 
type of index: the pemuted 
proceed as follows, 
nn, and nroff , case, the 
interprets the 
to make and prepares an 
Fran here you siirply feed the 
to uxiex, selects keyMoxds and 
words, to index, selects 
contexts. Hoe index is of 
iniexf ile > 
to pemuted index Since 
package, vhich the final index, 
you siinply feed the input to the 
want to include with your 
is a macro package dedicated to 
onptx. Like a concordance, the 
the 

another type of index: the 
print your 
Assuming you wanted to make a 
indexfile 
tutindex 



mdex lines are presented 
contextual words, to index, 
ei^ cptions, reads the file you 
index Since cptx is a macro 
index input, the name . . . 
index is a catalog mptx. 
index is of keywords and 
index itself. ... 

index made with, docdkehiqi'S hqrkeemch offers 
index mde with and another 
index of this tutorial, you would 
index was processed with mptsc, 
ii^put file ... 

input file that will be processed 
input to the nptx macro . 
isolates contextual vrords, 
keywords and isolates ocoitextiial 
keywords and their imnediate 
mm -liiptx . . . 

nptx is a ebcxo package dedicated 
nqpbc is a specialized macro 
uptx macro E^xm here .... 
permuted index. In the preceding 
pemuted index Since nptx 
pemit/^ index is a catalog 
pemuted index itself. . . . 
pemuted index made with and 

permuted index: 

pemuted tutorial above.) 

ptx file 

ptx -o subjfile tutorial 
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The index's keywords are the alphabetically ordered, left adjusted words at 
the center. Contextual words read from left to right. Notice that the con- 
textual phrase may begin at the far left or it may begin at with the key- 
word itself wrapping around, on the same line, to the left. This word order 
depends on the syntax of the original sentence. If the keyword occurs early 
in the sentence, the context is likely to wrap in the index. 

The permuted index used line adjustment (.ad) to make its contents 
easier to read. The left side is right adjusted, and the right side is left 
adjusted. 



NOIE 



For a complete listing of ptx and mptx options, see their manual entries in 
the Technical Discussion and Reference Manual, 
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Introduction 

This handbook, a memory jogger for accomplished users, reviews the 
commands and features of the DOCUMENTER'S WORKBENCH Software. If 
you need more information, refer to the User's Guide (310-004) or to the 
Technical Discussion and Reference Manual (310-005), If you are a beginner 
with the DOCUMENTER'S WORKBENCH Software, you might want to refer to 
the Handbook for New Users (310-009). 

This handbook is organized as follows: 

■ The *'Alphabetical List of Commands" section briefly describes 
the purpose of each formatting command, presents its com- 
mand line syntax and describes what its options do. 

■ The "mm Macros" section summarizes the macros for prepar- 
ing and formatting documents using the mm macro package. 

■ The "mv Macros" section summarizes the macros for prepar- 
ing and formatting view graphs and slides using the mv 
macro package. 

■ The "man Macros" section summarizes the macros for prepar- 
ing and formatting descriptions of commands in the style of 
UNIX manual pages using the man macro package. 

■ The "nro£f/tro£f Requests" section lists requests recognized by 
the nroff/troff formatter. 

■ The "Preprocessor Commands and Macros" section lists com- 
mands and macros you use with the tbl, eqn, neqn, and pic 
preprocessors. 

■ The "troff Characters" section presents the special characters 
available with troff. 

This handbook observes the following conventions when discussing 
command syntax: 

[] encloses an optional argument 

( ) encloses the default value for a register or string 

{} encloses a list of arguments from which one should be 

selected 
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italic text shows where you may substitute appropriate values 
bold text shows where you must type exactly what is specified 

Some sections of this handbook use additional conventions. These will 
be explained where they are used. You will have to check with your system 
administrator to determine which of the output devices listed in the com- 
mand descriptions is locally available. 
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Alphabetical List of Commands 

checkmm checks how you use Memorandum Macros (mm) and tbl 
and eqn delimiters 

checkmm [files] [— ] 

(Also, see the "mm Macros" section.) 



daps interprets files created by troff for the Autologic APS-5 

phototypesetter 

daps [-b] [-r] [-t] [-w] [-h string] [-o list] [-s n] [ — ] 
[files] [-] 

— b reports whether typesetter is busy; does not print output 

— r reports the number of 8.5x11 inch pages generated by 

the current job 

— t directs output to the standard output instead of the 

typesetter 

— w waits for typesetter to become free, then prints output 

— h string prints string in the current job's header 

— o list prints pages whose numbers you give in the list; separate 

page numbers or page ranges in the list with commas 
(e.g., 3,7-10) 

— s n stops after every n pages of output 

— delimits the end of options 

— reverts to the standard input 



diff mk marks differences between two versions of a file 

diffmk oldfile newfile dijfjile 

diff mk compares oldfile and newfile and generates dijf Jile, 
which when formatted, highlights the differences 
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between the old and new files, oldfile or newfile may be 
standard input. 



dilO interprets files created by troff for the Imagen Imprint- 

10 laser printer 

dilO [-0 list] [-t] [~] [files] H 

-o list prints pages whose numbers you give in the list; separate 

page numbers or page ranges in the list with commas 
(e.g., 3,7-10) 

-t directs output to the standard output instead of the 

typesetter 

— delimits the end of options 

- reverts to the standard input 



eqn translates eqn control lines into code that troff can use 

to typeset mathematical symbols 

[-d xy] [-P n] [-S n] [-( n] [-Tttyjype] [~] [files] [-] 

-d xy sets delimiters to x and y 

~p n changes point size factor n of subscripts and superscripts 

— s n changes point size to n 

— f n uses font number n 

—Tttyjype formats for device ttyjype 

— delimits the end of options 

- reverts to the standard input 

(Also, see neqn in this section and information about 
eqn in "Preprocessor Commands and Macros.") 
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g"p 


typesets graphs 




grap [-1] [~] [files] [-] 


-1 


does not load the standard define file from 




/usr/lib/grap.define 




delimits the end of options 




reverts to the standard input 


hyphen 


finds hyphenated words 




hyphen [files] [-] 


- 


reverts to the standard input 


macref 


produces a cross reference listing of macro files 




macref [-t] [-s] [-n] [ — ] file 


-t 


prints macro table of contents 


-s 


prints symbol-use statistics 


— n 


causes one line to be outDut for each reference to a svm- 




bol 


— 


delimits the end of options 


mm 


calls nroff to format files containing mm macros. (The 




following printer options also work with the nroff com- 




mand except where noted. Check with your local sys- 




tem administrator about any special printers.) 




mm [-e] [-rAn] [-t] [-c] [-E] [-12] [-Tttyjype] [files] [-] 


— e 


causes nroff to call neqn; also causes neqn to read the 




/usr/pub/eqnchar file 
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—rAn sets register A to n 

-t calls tbl 

— c calls col (see col(l) in the UNIX System V User's Reference 

Manual) 

— E calls the — e option of the nroff formatter 

—12 uses the 12-pitch mode; the pitch switch on the terminal 

should be set to 12 if necessary 

—Tttyjype prepares output for device ttyjype. Legal values of 
ttyjype include: 

2631 Hewlett-Packard 2631 printer in regular mode 

2631-c Hewlett-Packard 2631 printer in compressed mode 

2631-e Hewlett-Packard 2631 printer in expanded mode 

300 DASI-300 printer 

300-12 DASI-300 terminal set to 12-pitch (12 characters per 
inch) 

300s DASI-300S printer (300S is a synonym) 

300S-12 DASI-300S printer set to 12-pitch (12 characters per 
inch) (300S-12 is a synonym) 

37 Teletype Model 37 terminal (default for the nroff com- 

mand) 

382 DTC-382 

4000a Trendata 4000a terminal (4000A is a synonym) 

450 DASI-450 (Diablo Hyterm) printer 

450-12 DASI-450 terminal set to 12-pitch (12 characters per 
inch) 

832 Anderson Jacobson 832 terminal 
8510 C.ITOH printer 

Ip generic name for printers that can underline and tab. 

(AH text using reverse linefeeds, such as those having 
tables, that is sent to Ip must be processed with col.) 
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tnSOO GE Terminet 300 terminal 

X printers equipped with TX print train 

(Check with your system administrator for a list of 
locally supported devices.) 

reverts to the standard input 



mmt calls troff to typeset documents containing mm macros 

mmt [-e] [-rAn] [-t] [-p] [-g] [-Tttyjype] [-Ddest] [-a] 
[files] [-] 

— e calls eqn; also causes eqn to read the /usr/pub/eqnchar 

file 

—rAn sets register A to n 

-t calls tbl 

— p calls pic 

-g calls grap (which calls pic) 

—Tttyjype creates output for device ttyjype. Supported values for 
ttyjype are: 
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aps creates output for an Autologic APS-5 phototypesetter 
ilO creates output for an Imagen Imprint-10 laser printer 

—Ddest directs output to troff device dest. Supported values for 

dest are: 

4014 directs output to a TEKTRONIX 4014 terminal 

ilO directs output to an Imagen Imprint-10 laser printer 

—a calls the —a option of troff 

— z invokes no output filter to process or redirect the output 

of troff 

- reverts to the standard input 



mvt calls troff to typeset view graphs and slides containing 

mv macros 

mvt [-e] [-t] [-p] [-g] [-a] [-Tttyjype] [-Ddesf ] [-z] 
[-P] [troff options] [files] [-] 

-e calls eqn and has it read the /usr/pub/eqnchar file 

— t invokes tbl 

— p invokes pic 

-g invokes grap (which calls pic) 

—a directs output to your terminal using the —a option of 

troff 

-Tttyjype creates output for device ttyjype. Supported values for 
ttyjype are: 

4014 creates output for a TEKTRONIX 4014 terminal 

—Ddest directs output to troff device dest. Supported values for 

dest are: 
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4014 directs output to a TEKTRONIX 4014 terminal 

— z does not direct output to a post processor 

— p invokes pic 

— reverts to the standard input 

(AlsO/ see the section titled "mv Macros.") 

ndx creates an index 



ndx subj.file formatter j:ommandJine'' 

subj.file is the edited output from subj or a subject file 
that you create. An example of formatter j:ommandJine is: 

"mm -rW60 .rN2 file..,'' 

neqn translates neqn control lines into code that nro£f can use 

to format mathematical symbols 

neqn (see eqn above) 

nroff formats text for typewriter-like terminals 

nroff [-olist] [-nn] [-sn] [-rAn] [-1] [-q] [-z] [-mname] 
[-Tttyjype] [-e] [-h] [-un] [files] [-] 

—olist prints only pages whose page numbers you give in list; 

separate page numbers or page ranges in the list with 
commas (e.g., 3,7-10) 

— nw numbers first generated page n 

—sn stops after every n pages 

—rAn sets register i4 to n 
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— i reads standard input after files are exhausted 

-q invokes simultaneous input-output mode of .rd 

— z prints only messages generated by .tm requests 

—mnante uses name macro package 

-Tttyjype prepares output for device ttyjype (see range of terminal 
options with mm above) 

-e produces equally spaced words in adjusted lines 

-h uses output tabs during horizontal spacing to speed out- 

put and reduce output character count 

-un sets emboldening factor for third font position to n 

— reverts to the standard input 

(Also, see the "troff Characters" section.) 



pic translates pic control lines into code that troff can use to 

draw simple pictures 

pic [-Tttyjype] [— ] [files] [-] 

-Tttyjype adapts output for typesetter ttyjype (see range of 
typesetter options with mmt above) 

— delimits the end of options 

- reverts to the standard input 



ptx makes a permuted index 

ptx [-f ] [-1] [-W n\ [-g «] [-0 only] [-i ignore] [-b break] 
[-r] [~] \input[output]] [-] 

— f folds uppercase and lowercase letters for sorting 

— t prepeu-es output for phototypesetter 

— w n sets width of output line to n characters 
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— g n uses n characters to calculate gaps within a line 

— o only uses only keywords in only file 

-i ignore does not use keywords in the ignore file 

-b break uses characters in break file to separate words 

— r serves as a reference identifier 



sub) creates a list of subjects for an index 

sub) files 



tbl 


translates tbl control lines into code that nroff or troff 




can use to format tables 




tbl [-TX] [~] [files] [-] 


-TX 


puts out full vertical line motions only 




delimits the end of options 




reverts to the standard input 




(Also, see the section titled "Preprocessor Commands 




and Macros,**) 



tc interprets files created by troff for a TEKTRONIX 4015 

terminal (a 4014 terminal with ASCII and APL character 
sets) 

tc [-t ] [-0 list] [-a n] [-e] [~] [file] [-] 
-t does not wait between pages 

— o list prints only the pages that you give in list; separate page 

numbers or page ranges in the list with commas (e.g., 
3,7-10) 
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-a n sets the aspect ratio to n 

— e does not erase before each page 

— delimits the end of options 

— reverts to the standard input 

troff formats and typesets text 

troff [-olist] [-nn] [sn] [-rAn] [-i] [-q] [-z] [-mname] 
[-a] [-Tttyjype] [-Frfir] [files] [-] 

-olist prints only the pages that you give in list; separate page 

numbers or page ranges in the list with commas (e.g., 
3,7-10) 

-n« numbers first generated page n 

— sn stops after every n pages 

—rAn sets register A to n 

-i reads standard input after files are exhausted 

-q invokes simultaneous input-output mode of .rd 

~z prints only diagnostics and .tm messages 

—mmme uses macro package name 

-a sends printable ASCII approximation to standard output 

-Tttyjype prepares output for typesetter ttyjype (see range of 
typesetters with mmt above) 

--^dir accesses font information from directory dir/devname 

instead of the default /usr/lib/font/devnflmc (where 
name is your system's default output device) 

— reverts to the standard input 

(Also, see the section titled "troff Characters.") 
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The mm macros are used for memos, articles, research papers, and other 
standard prose. 



Beginning Macros for Formal Memoranda 



.ND date 

•TL [cftg#] [file#] 

.AF [company-name] 



new date 

title follows on next line 
alternative first-page format 



.AU name [initials] [loc] [dept] [ext] [room] [arg] ... 

author information 



.AT author-title [...] 

.TM [number] 

•AS [{012}] [indent] 



.AE 



title to follow signer's name (up to 9 arguments) 

technical memorandum number 

abstract start, for technical memorandum and 
released paper only 

= abstract on cover sheet and first page 

1 « abstract only on cover sheet 

2 " abstract only on Memorandum for File 
cover sheet 

abstract end 



notation start, allowed on Memorandum for File 
cover sheets following a AS 2/ AE macro pair 
(see the section "Ending Macros" below) 

notation end, allowed on Memorandum for File 
cover sheets following a AS 2/ AE macro pair 
(see the section "Ending Macros" below) 

other keywords (up to 9 arguments) 

.MT [{""0 1 23 4 5 string] ] [ [name l) ] 

document type 

=» = no type (internal letter) 

1 = memorandum for file 

2 = programmer's notes 

3 " engineer's notes 



.NE 



.OK [keyword ...] 
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mm Macros 

4 = released paper 

5 = external letter 
string « string printed 
name = addressee's name 

(cannot be used with released paper type) 
1 = list affiliation of each author 
(in released paper style only) 

.MT must occur after all cover sheet information 



Business Letter Macros 

writer's address start 
writer's address end 
confidential notation 
reference notation 
inside (recipient's) address start 
inside (recipient's) address end 
attention line 
salutation 
subject line 
] 

business letter type 
none = Blocked 
BL = Blocked 
SB = Semiblocked 
FB = Full-Blocked 
SP = Simplified 



Ending Macros (trailing information) 

.FC [closing] formal closing 



.WA 
.WE 

.LO CN [notation] 
XO RN [notation] 
.lA 
.IE 

.LO AT [notation] 

.LO SA [notation] 

.LO SJ [notation] 

.LT [ { none BL SB FB SP} 
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.SG [initials] [1] signature line 

.NS [ 1 2 3 4 5 6 7 8 9 10 11 12 13 string] ] 

notation start 



ttti 


S3 


Copy to 







Copy to 


1 




Copy (with att.) to 


2 


S3 


Copy (without att.) to 


3 




Att. 


4 




Atts. 


5 




Enc. 


6 




Encs. 


7 


a 


Under Separate Cover 


8 




Letter to 


9 




Memorandum to 



10 = Copy (with atts.) to 

11 = Copy (without atts.) to 

12 = Abstract Only to 

13 = Complete Memorandum to 
"^string"* = Copy (string) to 

.NE notation end 

.AV name [1] approval signature 

•CS \pgs] [other] [tot] [figs] [tbls] [ref] 

cover sheet 

.TX user exit for table-of-contents titles 

,TY user exit for table-of-contents header 

.TC [slev] [spacing] [tlev] [tab] [hi] [h2] [h3] [h4] [h5] 

table of contents 



Paragraphs 

•P [ ( 1 2 } 1 paragraph 

= left-justified (default) 

1 = indented 

2 =» indented except after .H, .LE, .DE 
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Section Headings 

.H (1 2 3 4 5 6 7} [headings 

.HU heading-text 

MM [l 0001 Aa I i} ... 



.HX dlev rlev heading-text 
.HY dlev rlev heading-text 
•HZ dlev rlev heading-text 



text] [footnote-mark] 
numbered headings 

unnumbered headings 

heading mark style 
1 — arable 

0001 - arabic with leading O's 
A uppercase alphabetic 
a - lowercase alphabetic 
I — uppercase roman 
i - lowercase roman 

user exit before headings 

user exit in the middle of headings 

user exit after headings 



Lists 



If the last argument [1] is present in the list-start macros, there will be 
no space between items. 

•AL [ {1 A a I i } ] [text-indent] [1] 

automatically-incremented list start (1) 

start a btdlet list 



.BL [text-indent] [1] 
.DL [text-indent] [1] 



start a dash list 



.ML mark [text-indent] [1] start a list in which each list item is tagged with 

mark. If text-indent is null or omitted it is set to 
[mark-width+1] 



.RL [text-indent] [1] 



start a reference list 



.VL text-indent [mark-indent] [1] 

start a variable tag list 
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^ ' mm Macros 

.LI [mark] [1] list item follows; 1 means that mark is to be 

prefixed to the current mark 

.LE [1] list end; 1 means to output a blank line after list 

(default: no blank line) 

.LB text-indent mark-indent pad type [mark] [{O l}] [{O l}] 

list begin 

type: 2=) 3=() 4=[] 5-0 6=1) 
6th argument: = no blank line before each list- 
item 

7th argument: = no blank line before list 
.LC [level] clear list-status up to level 



Displays, Tables, Equations, and Footnotes 

.DS [ {0 1 2 3 } ] [ {0 1 } ] [w] or .DS [ {L I C CB ) ] [ { N F } ] [«] 

start static display 
L = no indent 
I = indent from left 
C « center each line 
CB « center as a block 
N = no-fill 
F = fill 

n = indent from right n spaces 

.DF [ { 1 2 3 } ] [ { 1 } ] [n] or .DF [ { L I C CB ) ] [ {N F } ] [«] 

start floating display; 
arguments same as .DS 

.DE end display 

.FG [title] [override] [0 1 2] figure caption 

" prefix with override 

1 = suffix 

2 = replace 

.TS [H] start table; 

H =• multi page table 
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TH [N] 



.TE 



(miist be used when specifying argument H to 
TS) 

N = suppress table headers unless on top of new 
page 

(Also, see tbl in the section "Preprocessor Com- 
mands and Macros.") 

end table 



•TB [title] [override] [0 1 2] table caption 
.EX [title] [override] [0 1 2] exhibit caption 
.EQ [label] 
•EN 



start equation display 
end equation display 



(Also, see eqn and neqn in the section titled 
"Preprocessor Commands and Macros.") 



.EC [title] [override] [0 1 2] 
.FS [label] 
.FE 



equation caption 

start footnote 

end footnote 

.FD [ {0 1 2 3 4 ... 11} ] [1] footnote format 

1st argument « set up formatting style for foot- 
note text 

2nd argument = reset footnote counter on first- 
level heading 



Page Headers and Footers 

.PH neft' center right"' page header 

.OH neft' center rigW odd-page header 

.EH ""left' center right'"* even-page header 

.PF ""'left' center right'"* page footer 
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mm Macros 



.OF neft'center'right' 

.EF "'left'centerrighr 

.BS 

.BE 

.PX 

.TP 



odd-page footer 
even-page footer 
bottom-block start 
bottom-block end 
user exit for page-header 
top of page macro 



Miscellaneous Macros 

.B [argument] [prev-font-argument] 

bold (up to 6 arguments) 

.1 [argument] [prev-font-argument] 



italic (up to 6 arguments) 
.R return to roman font 

The following are for alternating fonts and all take 1 to 6 arguments: 

.IB alternate italic and bold 

,BI alternate bold and italic 

.RI alternate roman and italic 

JR alternate italic and roman 

.RB alternate roman and bold 

,BR alternate bold and roman 
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.PM [ arg ] proprietary marking 

arg for 

arg (DWB 1.0) DISCLAIMER MESSAGE 

PMl BP,N,P,BPN AT&T BELL LABORATORIES - PROPRIETARY 

Use pursuant to G.E.I. 2.2 

PM2 CA THIS DOCUMENT CONTAINS PROPRIETARY INFORMATION OF 

AT&T AND IS NOT TO BE DISCLOSED OR USED EXCEPT IN 
ACCORDANCE WITH APPLICABLE CONTRACTS OR AGREEMENTS 

PM3 CP SEE PROPRIETARY NOTICE ON COVER PAGE 

PM4 BPP.BR AT&T BELL LABORATORIES - PROPRIETARY (RESTRICTED) 

Solely for authorized persons having a need to know 
pursuant to G.E.I. 2.2 

PM5 ILL THIS DOCUMENT CONTAINS PROPRIETARY INFORMATION OF 

AT&T BELL LABORATORIES AND IS NOT TO BE DISCLOSED, 
REPRODUCED, OR PUBLISHED WITHOUT WRITTEN CONSENT. 
THIS DOCUMENT MUST BE RENDERED ILLEGIBLE WHEN 
BEING DISCARDED. 

PM6 CMI CI-II 

Not for disclosure to AT&T Information Systems. 
Subject to FCC separation requirements under Computer 
Inquiry II 

If you do not give .PM an argument, you turn off proprietary markings 

.RD [prompt] [diversion] [string] 

stop code macro 

•RP [ {0 l) ] [ (O 1 2 3} ] reference page 

1st argument: 

= reset reference counter (default) 

1 = do not reset reference counter 
2nd argument: 

= cause a .SK after (default) 

1 = do not cause a .SK after 

2 = do not cause a •SK before 

3 = do not cause a .SK before or after 
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.RS/.RF automatically numbered references 

.WC [ {N WF -WF FF -FF WD -WD FB -FB } ] 

width control for footnotes and displays when 
using 2 columns: 

N normal mode (-WF, -FF, -WD) 
WF footnotes always wide 
— WF footnotes follow page style 
FF first footnote determines width of 
remaining footnotes on that page 
— FF footnotes follow setting of WF, -WF 
WD always wide displays 
—WD displays follow page style 
FB floating display causes break (default) 
-FB floating display does not cause break 

.SP [lines] skip lines down 

.SK [pages] skip pages (go to next page) 

•OP force odd page start 

•2C print output in two columns 

•IC print output in one column (normal line width 

restored) 

•SA [argument] set right-margin justification 

argument = sets default to off 
argument = 1 sets default to on 
no argument reverts to current default 

.SM stringl [string!] [stringS] 

reduce size of stringl by 1 point if string3 omit- 
ted; otherwise, reduce size of stringl by 1 point 

•HC c set hyphenation character to c 
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.S [point size] [vertical spacing] 

set point size and vertical spacing 
defaults: point size = 10, 
vertical spacing=12p arguments 1 and 2: 
n « new value 

±« = increment to current value 

D = default 

C = current value 

P = previous value 

•VM [top] [bottom] vertical margins 

.nP double-line indent on paragraph start 



mm Registers 

If an asterisk follows a register name, that register can be set only one 
of two ways: 1) from the command line (see the -r option for mm in the 
section "Alphabetical List of Commands"), or 2) before the formatter reads 
mm macro definitions. In this list, the number shown in parentheses at the 
end of the line is the default value. 
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A * handle preprinted forms 

Au inhibit author information on first page (1) 

C * copy type (Original, DRAFT, etc.) (0) 

CI contents level (2) 

Cp placement of figures, tables, equations & exhibits (1) 

D * debug flag (0) 

De display eject register for floating displays (0) 

Df display format register for floating displays (5) 

Ds static display pre- & post-space (1) 

E * control font of the Subject /Date /From fields 

Ec equation counter 

Ej page-ejection flag for headings (0) 

Eq equation label placement (0) 

Ex exhibit counter 

Fg figure counter 

Fs footnote separation (1) 

HI . . . H7 heading counters 

Hb heading break level (after .H and .HU) (2) 

He heading centering level for .H and .HU (0) 

Hi heading temporary indent (after .H and .HU) (1) 

Hs heading space level (after .H and .HU) (2) 

Ht heading type: = concatenated numbers, 

1 = single numbers (0) 

Hu heading level for unnumbered heading (2) 

Hy hyphenation control: = no hyphenation (0) 

L * length of page (66v) 

Le list of equations 

Lf list of figures (1) 

Li list indent (5 troff ), (6 nroff) 

Ls list level down to which there is spacing between items (6) 

Lt list of tables (1) 

Lx list of exhibits (1) 

N * numbering style (0) 

Np numbered paragraphs: =» unnumbered, 1 = numbered (0) 

O * ofifset of page 

Oc page numbering style for table-of-contents: 

= lowercase roman, 1 = arable (0) 

Of figure caption style (0) 

F page number, managed by mm (0) 

Pi paragraph indent (5) 
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Ps paragraph spacing (1) 
Pt paragraph type (0) 

Pv PRIVATE header: = do not print PRIVATE 

1 = on first page only, 

2 = on all pages (0) 

Rf reference counter, used by .RS macro 

S * troff default point size (10) 

Si display indent (5) 

T * type of nroff output device (0) 

Tb table counter 

U * underlining style (nroff ) for .H and .HU (0) 
W * width of page (line and title length) 



mm Strings 

Print special strings by using the following escape sequences: 

\*x for strings with single character names (x) 
\*(xx for strings with two character names (xx) 

String Names 

BU bullet 

Ci indent of heading levels in the table of contents 

DT current date 

EM em-dash 

F footnote numberer 

HP heading level font string; 1 = roman, 

2 = italic, 3 » bold (2222222) 
HP point sizes of the various heading levels 
Le title of the list of equations 
Lf title of the list of figures 
Lt title of the list of tables 
Lx title of the list of exhibits 
RE sees SID of mm macros 
Rf reference numberer 
Rp title of the reference page 
Tm trademark 

grave accent 

acute accent 
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circumflex 
tilde 

: lowercase umlaut 
; uppercase umlaut 
/ cedilla 

Reserved Names 

If you define your own strings, macros, and registers, only use names 
that either consist of a single lowercase letter, or of a lowercase letter fol- 
lowed by any character other than a lowercase letter. The names c2 and nP 
are exceptions to this: they are already used. 
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The mv macros are used for making lecture materials such as view 
graphs and slides. 



Foil-Start Macros 



.VS [#] [who] [date] Starts a square view graph 

.Vw, .Vh, .VW, .VH, .Sw, .Sh, .SW, .SH 

Same as .VS, except that they start view graphs 
(V) or slides (S) that are small wide (w), small 
high (h), large wide (W), or large high (H). 
Recommended: .VS for square view graphs and 
slides, .Sw (and, if necessary, .Sh) for 35mm 
slides. 



Level Macros 

A [no-pre-space] return to left margin 

•B [mark [size]] go to first indent level (default mark is large bul- 

let); s is point size increment (0) 

.C [mark [size]] go to second indent level (default mark is em- 

dash) 

.D [mark [size]] go to third indent level (default mark is small 

bullet) 



Text-Control Macros 

.T string print string as a centered, enlarged title 

•I pwI'^Ml indent all text other than titles by in. Takes 

effect when the next level macro is called. If 
second argument is given, .A is called immedi- 
ately and the third argument is passed to it. 
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.S [size][line] change point size and/or line length. The first 

argument has the same effect as the first argu- 
ment to the mm macro of the same name. The 
second argument sets the line length. 

.U stringl [string!] literally underline stringl and concatenate string! 

to it. Not recommended. 



Default-Setting Macros 

.DV set the amount of prespace for level macros. 

Arguments must be scaled. Default values are 
.5v, .5v, .5v, Ov. 

.DF [n name] ... set font positions: takes up to four pairs of argu- 

ments of the form "2 etc. Must precede the 
first break in the input file (1 H 2 I 3 B 4 S). 



Miscellany 

The mv package accepts the following uppercase synonyms for the 
corresponding lowercase troff requests: 

.AD, .BR, .CE, .FI, .HY, .NA, .NF, .NH, .NX, .SO, .SP, .TA, .TI 
The Tm string produces a trademark symbol. 
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The man Macros are used to produce UNIX system manual pages. The 
text argument represents up to six "words"; if null, the entire next input text 
line is used as text. The in argument, if omitted, is set to its previous value. 



Format Macros 

.TH [f][s][c][M] set title and entry heading; 

t = title, s=section number 

c " extra commentary, n = new manual name 
.SH [text] place subhead text here 

.SS [text] place sub-subhead text here 

•B [text] make text bold 

.1 [text] make text italic 

•SM [text] make text 1 point smaller than default 

point size 

.RI [a][b] concatenate roman a with italic b; 

alternate these two fonts up to six 

arguments; similar macros alternate 

between any two of roman, italic, and 

bold: .IR, .RB, .BR, .IB, .BI 
.P begin paragraph with normal font, point 

size, and indent 
.HP [in] begin paragraph with hanging indent 

.TP [in] begin indented paragraph with hanging tag; 

next input line is the tag 
.IP [t][in] same as .TP in with tag t; if t is null, begin 

indented paragraph 
.RS [in] increase relative indent (initially zero) 

.RE [it] return to fcth relative indent level 

.PM [P N] proprietary marking 

P = PRIVATE 

N « NOTICE 

without argument, turn off proprietary marking 
.DT restore default tab settings 

.PD [v] set interparagraph distance v vertical spaces; 

default is 0.4v in troff , Iv in nroff 
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Strings 



R ® in troff, (Reg.) in nroff 

S revert to default type size 

Tm trademark 

Registers 

IN left margin indent relative to subheads 

LL line length including IN 

PD current interparagraph distance 
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nrof(/tro££ Requests 

This section provides easy access to the basic formatting requests of 
nroff/troff . Requests marked with a "f" are those that apply to troff only. 



Font and Character Size Control 



•ps ±N Point size; also \s±N.t 

•ss N Space-character size set to 

N/36em.t 

xsFNM Constant character space (width) 

mode (font F).t 
.bd F N Embolden font F by N-1 units.f 

.bd S F N Embolden Special Font when current font is F.| 

.ft F Change to font F = jc, xx, or 1-N, 

Also \fxMxxMN. 
Ap N F Font named F mounted on physical position KN. 

Page Control 

.pi ±N Page length. 

.bp ±N Begin next page; next page number N, 

•pn ±N Make next page number N. 

.po ±N Set page offset. 

.ne N Need N vertical space (V « vertical spacing). 

.mk R Mark current vertical place in register R. 

.rt ±N Return (upward only) to marked vertical place. 

Text Filling, Adjusting, and Centering 

.br Break. 

.£i Fill output lines. 

.nf No filling or adjusting of output lines. 

•ad c Adjust output lines with mode c. 

•na No output line adjusting. 

.ce N Center following N input text lines. 



30 HANDBOOK 



nroff/troff Requests 



Vertical Spacing 



.vs N 


Vertical base line spacing (V), 


AsN 


Output N— 1 Vs after each text output line. 


•sp N 


Space vertical distance N in either direction. 


.sv N 


Save vertical distance N, 


•OS 


Output saved vertical distance. 


•ns 


Turn no-space mode on. 


•rs 


Restore spacing; turn no-space mode off. 


Line Length and Indenting 


.11 ±N 


Line length. 


.in ±N 


Indent. 


.ti ±N 


Temporary indent. 


Macros, Strings, Diversions, and Position Traps 


.de XX yy 


Define or redefine macro xx; end at call of yy. 


.am XX yy 


Append to a macro. 


.ds XX string 


Define a string xx containing string. 


•as XX string 


Append string to string xx. 


.rm XX 


Remove request, macro, or string. 


.rn XX yy 


Rename request, macro, or string xx to yy. 


.di XX 


Divert output to macro xx. 


.da XX 


Divert and append to xx. 


.wh N XX 


Set location trap; negative is with respect to page bottom. 


.ch XX N 


Change trap location. 


.dt N XX 


Set a diversion trap. 


.it N XX 


Set an input-line count trap. 


•em XX 


End macro is xx. 
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Number Registers 

.nr R ±N M Define and set number register R; 

auto-increment by M. 
•af R c Assign format to register R (c-1, i, I, a. A), 

.rr R Remove register R. 



Tabs, Leaders, and Fields 

.ta Nt ... Tab settings; left type, unless ^-R (right), C (centered). 

.tc c Tab repetition character. 

.Ic c Leader repetition character. 

•fc a b Set field delimiter a and pad character b. 



Input and Output Conventions and Character Translations 



.ec c Set escape character. 

«eo Turn off escape character mechanism. 

Jg N Ligature mode on if N>0. 

•ul N Underline (italicize in troff ) N input lines. 

•cu N Continuous underline in nroff; like ul in troff . 

.u£ F Underline font set to F (to be switched to by ul). 

.cc c Set control character to c. 

.c2 c Set no-break control character to c. 

.tr abed..,. Translate a to b, etc., on output. 



Hyphenation 

•nh 

.hy N 
•he c 

•hw wordl ... 



No hyphenation. 
Hyphenate; N — mode. 
Hyphenation indicator character c. 
Exception words. 
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Three Part Titles 

.tl 'left'center'right' Three part title. 

•pc c Page number character. 

.It ±N Length of title. 



Output Line Numbering 

.nm ±N M S I Number mode on or off; set parameters, 
.nn N Do not number next N lines. 



Conditional Acceptance of Input 

.if c anything If condition c true, accept anything as input, 

for multi-line input use \{anyf/img\}. 

.if Ic anything If condition c false, accept anything. 

.if N anything If expression N > 0, accept anything. 

.if IN anything If expression N < 0, accept anything. 

.if 'stringl'stringl^ anything 

If stringl identical to string!, accept anything. 

.if Vstringl'stringl' anything 

If stringl not identical to string!, accept anything. 

.ie c anything If portion of if-else; all above forms (like if). 

.el anything Else portion of if-else. 



Environment Switching 

.ev N Switch environment {push down). 



Insertions from the Standard Input 

.rd prompt Read insertion. 

.ex Exit from nroff/troff. 
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Input/Output File Switching 

.so filename Switch source file (push down). 

.nx filename Next file, 

.cf filename Copy file. 

Jf N filename Change line number and file name, 

.pi program Pipe output to program. 



Miscellany 



.mc c N Set margin character c and separation N. 

.tm string Print string on terminal (UNIX standard message output). 

.ig yy Ignore till call of yy. 

.pm t Print macro names and sizes; 

if t present, print only total of sizes, 

.f 1 Flush output buffer, 

•ab text Suppress output but not error messages, 

.sy cmd args cmd executed but messages not put on standard output. 
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The following is a quick reference to the preprocessors, tbl, eqn, neqn, 
and pic. 

tbl 

Input Format 

[ {.DS .DF} ] 
.TS 

options ; 
format . 
data 
.TE 
[.DE] 

If you include short tables in an mm document, you should enclose them 
within the macro pair .DS (or .DF) and .DE. 

Options 



center 


center 


expand 


expand to line length 


box 


enclose in a box 


allbox 


box all entries 


doublebox 


enclose in two boxes 


tab(c) 


change tab character to c 


linesize(n) 


make all lines of thickness n points 


dehmixy) 


recognize x and y as eqn delimiters 




end of options 
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Format 



1 or 


L 


left-adjusted column 


r or 


R 


right-adjusted column 


c or 


C 


centered column 


n or 


N 


numerically-aligned column 


a or 


A 


left-adjusted subcolumn 


s or 


S 


horizontally spanned item 


t or 


T 


push vertical span to top 


V or 


V 


vertical line spacing 






vertically spanned item 


u or 


u 


move item V4 line up 


z or 


z 


zero-width item 






horizontal line 






double horizontal line 


1 




vertical line 


II 




double vertical line 


b or 


B 




i or 


I 


italic item 


fc or 


Fc 


font change to font c 


pn or Pm 


point-size change to size n 


w(«)or W(«) 


column width minimum = n 


nn 




spaces between columns 


e or 


E 


equal-width columns 






end of format 
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Data 



T{...T} 



text block 

Text blocks are used like this: 

data<TAB>T[ 
text block 
T]<TAB> data 



\Rjt 

V 

.TS H, •TH, and TE 



short horizontal line 

repeat x across column 

above item spans downward into this row 

start new format 

a variation of the table start/end macros that 
allows multi-page tables with column headings 
repeated on each page (this is a feature of the 
mm macros). (See the section titled •*mm Mac- 
ros.") 



eqn and neqn 



Input Format 

Displayed Equations: 

.DS (or .DF) 
.EQ 

equation 

.EN 

.DE 



In-line Equations: 

If you specify 
EQ 

delim ## 
.EN 

then the text may contain 
U equation U 
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If you include displayed equations in an mm document, you should enclose 
them in the macro pair .DS (or •DF)/.DE. 

Keywords 

sub sup over sqrt 

. . . from . . . to . . . 

left { [ I ( brackets right } ] | ) brackets 
pile { . . . above . . . ) 
Ipile cpile rpile 

dot dotdot hat bar 
tilde under vec dyad 
roman italic bold fat 
font / gf ont / 
delim define ndefine 

mark lineup 

up down fwd back 

matrix { col { . . . above . . . } col { . . . above 

Icol ccbl rcol 

sum int integral prod 

union inter 

>= <=!= — +- 

— > <— >> << approx 

sin cos tan tanh sinh cosh 

for if 

arc times lim 
max min 
log In exp 
prime cdot del half 

uppercase and lowercase Greek 

infinity inf 

partial grad nothing 
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Symbols defined in /usr/pub/eqnchar 



ciplus 




II 


II 


square 


□ 


citimes 




tansle 


/ 
\ 


circle 


o 


wis 




rangle 


/ 


blot 


■ 


—wis 




hbar 


H 


bullet 


• 


"^wis 


> 


vpd 

rr 


± 


vrov 


oc 




< 


<-> 




etnvtxi 









^ _ 




member 


c 


Star 


« 


I< 


< 


nomem 


i 


bigstar 


* 


l> 


> 


cup 


u 


''dot 








cap 


n 


orsign 


V 


rang 


L 


incl 


c 


andsign 


A 


3<<of 




subset 


C 


'^del 


& 


thf 




supset 


D 


oppA 


V 


quarter 


y4 


tsubset 


c 


oppE 


3 


3quarter 




tsupset 




angstrom 


A 


degree 


o 


scrL 




==< 


< 


— > 


> 







pic 

Pictures 

The top-level object in pic is the "picture": 
picture: 

.PS optional-width optional-height 

element-list 

.PE 

If optional-width is present, the picture is made that many inches wide, 
regardless of any dimensions used internally. The height is scaled in the 
same proportion unless optional-height is present. 

If .PF is used instead of .PE, the position after printing is restored to 
what it was upon entry. 
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Elements 

An element-list is a list of elements; the elements are 

shape attribute-list 
placename : element 
placename : position 
variable « expression 
direction 

{ list of elements ] 
[ list of elements ] 
for statement 
if statement 
copy statement 
print statement 
plot statement 
sh X commandline X 
troff'command 

Specify a placename with a capital letter 
followed by zero or more letters or numbers. 

Specify a variable with a letter 
followed by zero or more letters or numbers. 

Elements in a list must be separated by newlines or semicolons; a long 
element may be continued by ending the line with a backslash. Comments 
are introduced by a # and terminated by a newline. 

Variable names begin with a lower case letter; place names begin with 
upper case. Place and variable names retain their values from one picture 
to the next. 

The current position and direction of motion are saved upon entry to a 
{«.) block and restored upon exit. 

Elements within a block enclosed in [.•.] are treated as a unit; the 
dimensions are determined by the extreme points of the contained objects. 
Names, variables, and direction of motion within a block are local to that 
block. 
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troff'Command is any line that begins with a period. Such lines are 
assumed to make sense in the context where they appear. 

Primitives 

The primitive objects are 
primitive: 

box 

circle 

ellipse 

arc 

line 

arrow 

spline 

move 

text-list 

arrow is a synonym for line — >. 
Attributes 

An attribute-list is a sequence of zero or more attributes; each attribute 
consists of a keyword, perhaps followed by a value. In the following, e is 
an expression and opt-e an optional expression. 

attribute: 



h(eigh)t e 


wid(th) e 


rad(ius) e 


diam(eter) e 


up opt-e 


down opt-e 


right opt-e 


left opt-e 


from position 


to position 


at position 


with corner 


by e, e 


then 


dotted opt-e 


dashed opt-e 


chop opt—e 


-> <- <- 


invis 


same 


text-list 
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Missing attributes and values are filled in from defaults. Not all attri- 
butes make sense for all primitives; irrelevant ones are silently ignored. 
These are the currently meaningful attributes: 

box: 

height, width, at, same, dotted, dashed, invis, text 
circle, ellipse: 

radius, diameter, height, width, at, same, invis, text 

arc: 

up, down, left, right, height, width, from, to, at, radius, 
invis, cw, <->, text 

line, arrow: 

up, down, left, right, height, width, from, to, by, then, at, 
same, dotted, dashed, invis, <-,->,<->, text 

spline: 

up, down, left, right, height, width, from, to, by, then, at, 
same, invis, <-,->, <->, text 

move: 

up, down, left, right, to, by, same, text 

text-list: 

at, text-item 

The attribute at implies placing the geometrical center at the specified place. 
For lines, splines and arcs, height and width refer to arrowhead size. 

Text 

Text is normally an attribute of some primitive; by default it is placed at 
the geometrical center of the object. Stand-alone text is also permitted. A 
text-list is a list of text items; a text item is a quoted string optionally fol- 
lowed by a positioning request: 

text-item: 

It « 

center 

ljust 

rjust 

above 

below 

If there are multiple text items for some primitive, they are centered verti- 
cally except as qualified. Positioning requests apply to each item indepen- 
dently. 
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Text items can contain troff commands for size and font changes, local 
motions, etc., but make sure that these are balanced so that the entering 
state is restored before exiting. 

Positions and Places 

A position is ultimately an x,y coordinate pair, but it may be specified in 
other ways. 

position: 
place 

( position ) 

expression, expression 

( position ) [± (expression, expression)] 

( position ) [± expression, expression] 

( placel, place! ), i.e., ( placehx, place2,y) 

expression < position , position > 

expression [of the way] between position and position 

place: 

placename [corner] 
corner placename 
Here 

corner of nth shape 
nth shape [comer] 

A corner is one of the eight compass points or the center or the start or end 
of a primitive. 

comer: 

•n *e .w .s .ne .se .nw .sw 
•t •b .r .1 
•c .start .end 

Each object in a picture has an ordinal number; nth refers to this. 
nth: 

nth 

nth last 

Since pic is flexible enough to accept names like 1th and 3th, synonyms like 
1st and Sst are accepted as well. 
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Variables 

The built-in variables and their default values are: 

boxwid 0,75 boxht 0,5 

circlerad 0.25 arcrad 0.25 

ellipsewid 0.75 ellipseht 0.5 

linewid 0.5 lineht 0.5 

movewid 0.5 movewid 0.5 

arrowwid 0.05 arrowht 0.1 

textwid textht 
dashwid 0.5 
scale 1 

These may be changed at any time, and the new values remain in force 
from picture to picture until changed again. 

The variables textht and textwid may be set to any values to control 
positioning. The width and height of the generated picture may be set 
independently from the .PS line. Variables changed within and T revert 
to their previous value upon exit from the block. Dimensions are divided 
by scale during output. 

Expressions 

Expressions in pic are evaluated in floating point. All numbers 
representing dimensions are taken to be in inches. 
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expression: 



e e 



e — e 



e * e 



e I e 

e % e (modulus) 



— e 



{e) 



variable 
number 

place .X 
place .y 
place .ht 
place .wid 
place .rad 

sin(e) cos(e) atan2(e,e) log(e) sqTi(e) int(e) 
max(e,e) min(£r^e) rand(e) 



Logical Operators 

pic provides the following operators for logical evaluation: 



Definitions 

The define statement is not part of the grammar, 
define: 



> 
< 
> 

3&& 



(not) 

(greater than) 
(less than) 

(greater than or equal to) 
(less than or equal to) 
(and) 
(or) 

(equal to) 
(not equal to) 



define name X replacement text X 
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Occurrences of $1, $2, etc., in replacement text will be replaced by the 
corresponding arguments if name is invoked as 

name(argl, argl, ...) 

Non-existent arguments are replaced by null strings. Replacement text may 
contain newlines. 

copy and copy thru Statements 

The copy statement includes data from a file or that follows immedi- 
ately: 

copy "/i/e" 

copy thru macro 

copy "/t/e" thru macro 

copy "/i7e" thru macro until "sfrm^" 

The macro may be either the name of a defined macro, or the body of a 
macro enclosed in some character not part of the body. If no filename is 
given, copy copies the input until the next •?£. 

for Loops and if Statements 

The for and if statements provide for loops and decision-making: 

var='expr to expr by expr do X anything X 
if expr then X anything X else X anything X 

The by and else clauses are optional. The expr in an if may use the usual 
relational operators or the string tests strl «= (or ) str2. 

Miscellany 

The sh command executes a command line: 
sh X commandline X 

It is possible to plot the value of an expression: 

plot expr opt-format attributes 

The expr is evaluated and converted to a string (using the format 
specification if provided). 
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The state of fill or no-fill mode is preserved around a picture. 
Input numbers may be expressed in E (exponential) notation. 
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Standard Characters 



ABCDEFGHIJKLMNOPQRSTUVWXYZ 
abcdefghijklmnopqrstuvwxyz 

0123456789 
$!%&()• + .,:;/?-[]! 
©#"<>{}-- 



Escape Sequences for Special Characters 

(open quote) 
' (close quote) 
— \— (minus) 

\(hy or - 





\(ein 


• 


\(bu 


□ 


\(sq 




\(ru 


V* 


\(14 


Vi 


\(12 




\(34 


fi 


\(fi 


fl 


\(fl 




\(ff 


ffi 


\(Fi 


m 


\(F1 





\(de 


t 


\(dg 




\(fm 


<t 


\(ct 


• 


\(rg 


e 


\(co 
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\ 



+ 


\(pl 




\(mi 




\(eq 


* 




8 


\(sc 




\(aa 




\(ga 




\(ul 


7 


\(sl 


OL 


\(*a 




\(*b 


y 


w o 


d 


\(*d 


6 


\(*e 


t 
i 


\(*z 


7J 


\(*y 


e 




i 




K 


\(*k 


X 


\(*1 


u 


\(*m 




\(*n 




\(*c 





\(*o 


TT 


\(*P 


P 


\{*r 




\Cs 


9 


\(ts 


T 


\(*t 


U 


\(*u 




\Cf 


X 


\{*x 




\(*q 


0) 


\(*w 



A \CA 

B \(*B 

r \(*G 

A \(*D 

E \(»E 

Z \(*Z 

H \(»Y 

e \CH 

1 \(*I 
K \(*K 
A \(*L 
M \(*M 
N \(*N 
E \(*C 
\(*0 
n \CP 
P \(*R 

2 \CS 
T \(*T 

Y \(*U 
* \(*F 
X \CX 

^ \(*Q 

ft \(*W 

V \(sr 
\(rn 

> \(>= 

< \(<= 

I 

~ \(ap 
\(!- 

- \(-> 

- \«- 
t \(ua 



i 


\(da 


X 


\(mu 




\(di 


± 


\(+- 


u 


\(cu 


n 


\(ca 


c 


\(sb 


D 


\(sp 


C 


\(ib 


D 


\(ip 

*v XT 


oo 


\(if 


d 


\(pd 


V 


\(gr 




\(no 


/ 


\(is 


oc 


\(pt 





\(es 


€ 


\(mo 


1 


\(br 




\(dd 




\(rh 




\(lh 


1 


\(or 


O 


\(ci 




\(lt 




\(lb 


1 


\(rt 




\(rb 




\(lk 




\(rk 




\(bv 




\(lf 




\(rf 




\(lc 




\(rc 
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ASCII Character Set 

In octal code: 



000 nul 


001 soh 


004 eot 


005 enq 


010 bs 


Oil ht 


014 np 


015 cr 


020 die 


021 del 


024 dc4 


025 nak 


030 can 


031 em 


034 fs 


035 gs 


040 sp 


041 ! 


044 $ 


045 % 


050 ( 


051 ) 


054 , 


055 - 


060 


061 1 


064 4 


065 5 


070 8 


071 9 


074 < 


075 = 


100 @ 


101 A 


104 D 


105 E 


110 H 


111 I 


114 L 


115 M 


120 P 


121 Q 


124 T 


125 U 


130 X 


131 Y 


134 \ 


135 ] 


140 ' 


141 a 


144 d 


145 e 


150 h 


151 i 


154 1 


155 m 


160 p 


161 q 


164 t 


165 u 


170 X 


171 y 


174 1 


175 } 



002 stx 


003 etx 


006 ack 


007 bel 


012 nl 


013 vt 


016 so 


017 si 


022 dc2 


023 dc3 


026 syn 


027 etb 


032 sub 


033 esc 


036 rs 


037 us 


042 " 


043 # 


046 & 


047 ' 


052 • 


053 + 


056 . 


057 / 


062 2 


063 3 


066 6 


067 7 


072 : 


073 ; 


076 > 


077 ? 


102 B 


103 C 


106 F 


107 G 


112 J 


113 K 


116 N 


117 O 


122 R 


123 S 


126 V 


127 W 


132 Z 


133 [ 


136 * 


137 


142 b 


143 c 


146 f 


147 g 


152 j 


153 k 


156 n 


157 o 


162 r 


163 s 


166 V 


167 w 


172 z 


173 { 


176 ■ 


177 del 
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In hexadecimal code: 



00 nul 


01 soh 


02 stx 


03 etx 


04 eot 


05 enq 


06 ack 


07bel 


08 bs 


09 ht 


Oa nl 


Ob vt 


Oc np 


Od cr 


Oe so 


Of si 


10 die 


11 del 


12 dc2 


13 dc3 


14 dc4 


15 nak 


16 syn 


17 etb 


18 can 


19 em 


la sub 


lb esc 


Ic fs 


Id gs 


le rs 


If us 


20 sp 


21 ! 


22 " 


23 # 


24 $ 


25 % 


26 & 


27 ' 


28 ( 


29 ) 


2a • 


2b + 


2c , 


2d - 


2e . 


2f / 


30 


31 1 


32 2 


33 3 


34 4 


35 5 


36 6 


37 7 


38 8 


39 9 


3a : 


3b ; 


3c < 


3d = 


3e > 


3f ? 


40 @ 


41 A 


42 B 


43 C 


44 D 


45 E 


46 F 


47 G 


48 H 


49 I 


4a J 


4b K 


4c L 


4d M 


4e N 


4f O 


50 P 


51 Q 


52 R 


53 S 


54 T 


55 U 


56 V 


57 W 


58 X 


59 Y 


5a Z 


5b [ 


5c \ 


5d ] 


5e * 


5f 


60 ' 


61 a 


62 b 


63 c 


64 d 


65 e 


66 f 


67 g 


68 h 


69 i 


6a j 


6b k 


6c 1 


6d m 


6e n 


6f o 


70 p 


71 q 


72 r 


73 s 


74 t 


75 u 


76 V 


77 w 


78 X 


79 y 


7a z 


7b { 


7c 1 


7d } 


7e ' 


7f del 



HANDBOOK 51 



310-007 
Issue 1 



UNIX"" System V 

DOCUMENTER'S WORKBENCH™ 
Software Release 2.0 

Release Notes 



©1986 AT&T 

All Rights Reserved 

Printed in USA 

NOTICE 

The information in this document is subject to change without notice. AT&T 
assumes no responsibility for any errors that may appear in this document. 

9700 is a trademark of Xerox. 

APS-5 is a trademark of Autologic. 

DOCUMENTER'S WORKBENCH is a trademark of AT&T 

IMPRINT is a trademark of IMAGEN. 

PDP is a trademark of Digital Equipment. 

UNIX is a trademark of AT&T 

VAX is a trademark of Digital Equipment. 



L-243660-16 



Table of Contents 



Introduction i 

Installation 2 

Installing Source Code on the 3B20 Computer 2 

Reading Source Code from the Distribution Tape 2 

Building the DOCUMENTER'S WORKBENCH Software 3 

Installing Source Code on VAX Computers 3 

Reading Source Code from the Distribution Tape 3 

Building the DOCUMENTER'S WORKBENCH Software 4 

Installing Source Code on the 3B5 Computer and the 3B15 Computer 5 

Reading Source Code from the Magnetic Tape 5 

Reading Source Code from a Lark II Disk Cartridge 6 

Building the DOCUMENTER'S WORKBENCH Software 7 

Installing Binary Code on the 3B5 Computer 7 

Reading Binary Code from the Distribution Tape 7 

Removing Binary Code from the 3B5 Computer 9 

Installing DOCUMENTER'S WORKBENCH Software on 

the 3B2 Computer 9 

Prerequisites 10 

Disk Space Requirements 10 

Contents 10 

Installation Procedure 18 

Removing DOCUMENTER'S WORKBENCH Software from 

the 3B2 Computer 18 

Documents for the DOCUMENTER'S WORKBENCH 

Software 19 

Warnings 20 



TABLE OF CONTENTS Hi 



Table of Contents 

Upgrading from Release 1.0 to Release 2.0 21 

Changes 21 

Defining Memo Headings with strings.mm 23 

Appendix 1: Source Files 26 

Appendix 2: Manual Pages 39 

Appendix 3: Executable Files 4i 

Appendix 4: Converting Terminal Description Files 

to ASCn Format 49 

Appendix 5: Software Notes 52 



iv RELEASE NOTES 



Introduction 



This document provides important information concerning the installa- 
tion of the DOCUMENTER'S WORKBENCH Software Release 2.0. Please read 
this document carefully before attempting the installation procedure. 

Customers who have used UNIX system text processing software before 
will find this release of the DOCUMENTER'S WORKBENCH Software 
significantly improved. Because the majority of changes are compatible 
with earlier releases of DOCUMENTER'S WORKBENCH tools, documents that 
previously formatted correctly should continue to process properly. Docu- 
ments that previously had formatting problems may now format correctly. 
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Installation 



This section guides you in the installation of the DOCUMENTER'S WORK- 
BENCH Software Release 2.0. Before you begin, you will probably find it 
helpful to read through the instructions for the computer on which the 
DOCUMENTER'S WORKBENCH Software will be installed: 3B20 Computer, 
VAX Computer, 3B15 Computer, 3B5 Computer, or 3B2 Computer. Before 
beginning any installation it is best to familiarize yourself with the product 
and the procedure. 

Installing Source Code on the 3B20 Computer 

This section tells you how to read the source code from its release tape 
and install it in the proper directories. 

Reading Source Code from the Distribution Tape 

The source code is distributed on a single magnetic tape containing two 
files in cpio format, written at 1600 bpi. The tape may be read by a system 
administrator with root user-id privileges, from the magnetic tape drive 
labeled "0." 

The first file contains the eatable manual entries (a list of which is 
included in Appendix 2). To read these into the /usr/catman directory, use 
the following commands: 

# cd /usr/catman 

# cpio -idcv < /dev/rmt/Omn 

# 

(Alternatively, the manual entries may be read into a local catman directory 
structure by executing the cd command into that directory instead of into 
/usr/catman.) 

If you do not wish to have these manual entries on your system, execute 
the following command instead: 

# < /dev/rmt/Omn 
# 
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The second file on the tape contains all the source files to be installed in 
/usr/src/cmd/text. A list of the source files is included in Appendix 1. 
Use the following commands to read them in: 

# cd /usr/src/cmd 

# epic -idcv < /dev/rmt/Om 

# 

You have now completed reading the source code and may proceed to 
build the executable programs. 

Building the DOCUMENTER'S WORKBENCH Software 

To build Release 2.0 object code, the system administrator should, again, 
be logged into the UNIX system, with root user-id privileges. The UNIX sys- 
tem may be running in multi-user mode as long as no one else is using any 
existing text processing software. Use the following command to build the 
DOCUMENTER'S WORKBENCH Software: 

# /usr/src/:mkcmd text col 
# 

This command will compile and install all the commands and data files 
for the DOCUMENTER'S WORKBENCH Software. It will take approximately 
five hours and will produce many lines of output to the terminal. You may 
want to redirect the output to a file. 



Installing Source Code on VAX Computers 

This section tells you how to read the source code from its release tape 
and install it in the proper directories. 

Reading Source Code from the Distribution Tape 

The source code is distributed on a single magnetic tape containing two 
files in epic format, written at 1600 bpi. The following instructions for 
reading the tape are written for users of the VAX-11/780 and 11/750 proces- 
sors. 
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The tape may be read by a system administrator with root user-id 
privileges, from the magnetic tape drive labeled "0." 

The first file on the tape contains the eatable manual entries (a list of 
which is included in Appendix 2). To read these into the /usr/catman 
directory, use the following commands: 

# cd /usr/catman 

# cpio -idcv < /dev/rmt/Omn 
# 

Alternatively, the manual entries may be read into a local eatable directory 
structure by executing the ed command into that directory instead of into 
/usr/catman. 

If you do not wish to have these manual entries on your system, execute 
the following command instead: 

# < /dev/rmt/Omn 
# 

The second file on the tape contains all the source files to be installed in 
/usr/src/cmd/text. A list of source files is included in Appendix 1, Use 
the following commands to read them in: 

# cd /usr/src/cmd 

# cpio -idcv < /dev/rmt/Om 
# 

You have now completed reading the source code and may proceed to 
build the executable programs. 

Building the DOCUMENTER'S WORKBENCH Software 

To build Release 2.0 object code, the system administrator should, again, 
be logged into the UNIX system, with root user-id privileges. The UNIX sys- 
tem may be running in multi-user mode as long as no one else is using any 
existing text processing software. Use the following command: 

# /usr/src/:mkcmd text col 
# 
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This command will compile and install all the commands and data files 
of the DOCUMENTER'S WORKBENCH Software. It will take approximately 
five hours and will produce many lines of output to the terminal. You may 
want to redirect the output to a file. 

Installing Source Code on the 3B5 Computer and the 
3B15 Computer 

This section describes the procedures for reading the source code from 
its release media and installing it into the proper directories. 

The source code for the 3B5 Computer and 3B15 Computer is distributed 
on either a Lark II disk cartridge or a single magnetic tape containing two 
files in cpio format, written at 1600 bpi. 

The media may only be read by a system administrator with root user-id 
privileges. 

Reading Source Code from the Magnetic Tape 

If the release media is a magnetic tape, mount the tape on drive "0." 
The first file on the tape contains the eatable manual entries (listed in 
Appendix 2). To read these into the /usr/catman directory, use the follow- 
ing commands: 

# cd /usr/catman 

# cpio -idcv < /dev/rmt/Omn 
# 

Alternatively, the manual entries may be read into a local catman directory 
structure by executing the cd command into that directory instead of into 
/usr/catman* 

If you do not wish to have these manual entries on your system, execute 
the following command instead: 

# < /dev/rmt/Omn 

# 
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The second file on the tape contains all the source files to be read into 
/usr/src/cmd/text. A list of the source files is included in Appendix 1. 
Use the following commands to read them in: 

# cd /usr/src/cmd 

# cpio -idcv < /dev/rmt/Om 
# 



Reading Source Code from a Lark II Disk Cartridge 

The first file on the cartridge contains the eatable manual entries (listed 
in Appendix 2). Insert the cartridge and type the following commands: 

# mount /dev/dsk/D52 /mnt -r 

# cd /usr/catman 

# cpio -idcv < /mnt/catman.cpio 
# 



NOTE 



In the mount command, D stands for the drive number [1, 2, or 3], and 2 is 
ine partition number. 



Alternatively, the manual entries may be read into a local catman directory 
structure by executing the cd command into that directory instead of into 
/usr/catman. 

If you do not wish to have these manual entries on your system, do not 
execute the cd and cpio commands. You will still need to execute the 
mount command. 

The second file on the cartridge contains all the source files to be 
installed in /usr/src/cmd/text A list of the source files is included in 
Appendix 1, To read these into /usr/src/cmd/text, execute the following 
commands: 

# cd /usr/src/cmd 

# cpio -idcv < /mnt/dwb.cpio 
# 
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You have now completed reading the source code and may proceed to 
build the executable programs. 

Building the DOCUMENTER'S WORKBENCH Software 

To build Release 2.0 object code, the system administrator should be 
logged into the UNIX system with root user-id privileges. The UNIX system 
may be running in multi-user mode as long as no one is using any existing 
text processing software. Use the following command: 

# /usr/src/:mkcmd text col 
# 

This command will compile and install all the commands and data files 
of the DOCUMENTER'S WORKBENCH Software. It will take approximately 
five hours and will produce many lines of output to the terminal. You may 
want to redirect the output to a file. 



Installing Binary Code on the 3B5 Computer 

The DOCUMENTER'S WORKBENCH Software binary product for the 3B5 
Computer and the 3B15 Computer, is distributed on a single magnetic tape 
containing two files in epic format, written at 1600 bpi. This product 
requires approximately 6560 blocks of free space in the /usr file system. 
Your 3B5 Computer or 3BI5 Computer will give frequent prompts and pro- 
gress messages to guide you. 

Installation of DOCUMENTER'S WORKBENCH Software is simple. 
Instructions and error messages are displayed to guide you through the pro- 
cess. 

Reading Binary Code from tlie Distribution Tape 

The tape may be read by a system administrator with root user-id 
privileges, from magnetic tape drive labeled "0," Read the installation pro- 
cedure file onto the hard disk using the following command: 

# cpio -iBdmuv < /dev/rmt/Omn 

# 
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This command directs the system to read the first file on the tape. The 
first file contains several smaller files, needed for the installation procedure, 
which are read from the tape into the /tmp directory. As each file is read, 
its name will appear on your display screen as shown below. 



/tnp/INSTALL 
/tnp/REAEME 
/tnivUNINSTALL 
/tnp/preinstall 
/tnqp/postinstall 
/tup/dwb . name 
./tnp/W.ist 



All commands and eatable manual entries for DOCUMENTER'S WORK- 
BENCH Software are on the second file. The eatable manual entries and 
binary files are listed in Appendix 2 and Appendix 3, respectively. To run 
the installation procedure, type: 

# /tmp/INSTALL 

# 

The system will display the name of the application and release number 
as follows: 

DOCUMEMTER'S VO^KBEMCH SOPIWARE, Release 2.0 

This is followed by various prompts to guide you through the installation of 
DOCUMENTER'S WORKBENCH Software. 



Nore 



For additional information on installation procedures, use the "AT&T 3B5 
Computer Installation Guide" described in the AT&T 3B5 Computer 
Owner I Operator Manual. 
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Removing Binary Code from the 3B5 Computer 

Uninstall procedures for the 3B5 Computer and the 3B15 Computer fol- 
low the same steps as the install process. The system administrator should 
be logged into the UNIX system with root user-id privileges, after loading 
the tape onto the tape drive labeled "O." Read the uninstall procedure file 
onto the hard disk using the following command: 

# epic -iBdmuv < /dev/rmt/Om 
# 

To run the uninstall procedure, type: 

# /tmp/UNINSTALL 

# 

Prompts and progress messages will guide you from there on. 

Installing DOCUMENTER'S WORKBENCH Software on 
the 3B2 Computer 

All commands and data for DOCUMENTER'S WORKBENCH Software are 
on four floppy diskettes, labeled as follows: 

DOCUMENTER'S WORKBENCH Software Release 2.0 

The following UNIX System V utilities must be installed before 
DOCUMENTER'S WORKBENCH Software can be installed: 

Directory and File Management Utilities 
Terminal Filters Utilities 

Installation of DOCUMENTER'S WORKBENCH Software is simple. Instruc- 
tions and error messages are displayed on your terminal screen to guide you 
through the process. In the following paragraphs, information that you 
enter on the keyboard must be followed by a carriage return. (This is indi- 
cated in the text by a <CR> at the end of such lines.) 
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Prerequisites 

Before starting the installation, you should decide whether your applica- 
tion requires the fourth diskette. The fourth diskette contains the software 
for the Imagen Imprint-lO laser printer. The installation procedure will ask 
if you want the fourth diskette installed. If you do not have an Imagen 
printer, answer no; otherwise, answer yes. 

Disk Space Requirements 

The installation of the DOCUMENTER'S WORKBENCH Software requires 
either 3200 or 5500 (with disk 4) free blocks in the /usr file system. The 
root (/) file system needs no free blocks. The installation process checks 
that the required free disk space is available for the installation of the pro- 
duct. 

If sufficient disk space is not available, you will need to uninstall 
(remove) other optional utilities packages (or unwanted files or directories) 
to make space available to install this product. Uninstall procedures are dis- 
cussed later. 



Contents 

The first floppy diskette contains the files needed to use device- 
independent troff, plus a driver and the font tables for the driver. The 
driver is the Autologic APS-5 typesetter. This diskette requires approxi- 
mately 1100 blocks of free space in the /usr file system. This diskette con- 
tains the files: 



/usr/bin/daps 
/usr/bin/eqn 
/usr/bin/grap 
Vusr/bin/mmt 
/usr/bin/mvt 
/usr/bin/pic 
/usr/bin/tc 
/usr/bin/troff 
/ usr / lib / d wb / grap.defines 
/ usr/lib/f ont/devaps/B.add 
/ usr/lib/f ont/devaps/B*out 
/usr/lib/font / de vaps / Bl.out 
/usr/lib/font / de vaps / Cou t 
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/ usr / lib / font / de vaps / R.add 

/usr/lib/font/devaps/R.out 

/ usr / lib / f on t / de vaps / S.add 

/usr/lib/font/devaps/S.out 

/ usr / lib / f on t / de vaps / Sl.add 

/ usr / lib / f on t / de vaps / Sl.out 

/usr/lib/font/devaps/SCadd 

/usr/lib/font/devaps/SCout 

/ usr / lib / f on t / de vaps/ SM.add 

/ usr / lib / font / devaps / SM.ou t 

/usr/lib/font/devaps/TB.out 

/usr/lib/font/devaps/TX.add 

/usr/lib/font/devaps/TX.out 

/ usr / lib / f on t / devaps / version 

/ usr / options / d wb^name 

/ usr / pub / apseqnchar 

/ usr / pub / cateqnchar 

/ usr/pub/eqnchar 

/ usr / lib / readme / d wb 

The second floppy disk contains all the files needed to use nroff . This 
includes neqn and mm. The files contained on this floppy disk require 
approximately 750 blocks of free space in the /usr file system. This diskette 
contains the following files: 

/ usr / bin / checkmm 

/ usr / bin / checkmml 

/usr/bin/col 

/usr/bin/macref 

/usr/bin/mm 

/usr/bin/neqn 

/usr /bin /nroff 

/ usr / lib / n term / tab.2631 

/ usr / lib / n term / tab.2631-c 

/ usr / lib / n term / tab.2631-e 

/ usr / lib / n term / tab.300 

/ usr / lib / nterm / tab.300-12 

/ usr / lib / nterm / tab.300S 

/usr/lib/nterm/tab.300S-12 

/ usr / lib / nterm / tab.300s 

/usr / lib / nterm / tab.?00s-12 

/ usr / lib / nterm / tab.37 
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/usr/lib/nterm/tab.382 
/usr/lib/nterm/tab.4000A 
/ usr / lib / n term / tab.4000a 
/ usr/ lib / nterm / tab.450 
/ usr / lib / nterm / tab-450-12 
/ usr / lib / nterm / tab.832 
/usr/lib/nterm/tab-8510 
/usr/lib/nterm/tab.X 
/ usr / lib / nterm / tab.lp 
/ usr / lib / nterm / tab.tnSOO 
/ usr / pub / terminals 

The third floppy diskette contains files that are used by both nroff and 
troff, plus files upon which both nroff and troff depend. The files con- 
tained on this diskette require 1300 blocks of free space in the /usr file sys- 
tem. This diskette contains the following files: 

/usr/bin/diffmk 

/ usr / bin / hyphen 

/usr/bin/ndx 

/usr/bin/ptx 

/usr/bin/subj 

/usr/bin/tbl 

/ usr / lib / d wb / deroff 

/ usr/lib/dwb/ndexer 

/ usr /lib/ d wb / ndxf or mat 

/ usr /lib/ d wb / pages 

/ usr /lib/ d wb / parts 

/ usr/lib/dwb/samples/eqn.stats 

/ usr/lib/dwb/samples/mm.letter 

/ usr/lib/dwb/samples/mm.report 

/ usr/lib/dwb/samples/mm.sales 

/usr/lib/dwb/samples/nroff.letter 

/ usr/lib/dwb/samples/pic.forms 

/ usr / li b / dwb /samples / tbLbridges 

/ usr / lib / dwb / samples / tbLlanguage 

/ usr / lib / dwb /samples / tbLpres 

/ usr/ lib /dwb /samples/ trofiF.ad 

/ usr / lib / dwb /samples / troff «aeneid 

/ usr / lib / dwb / samp les / troff .fan ts 

/ usr/lib/dwb/samples/troff .sizes 

/usr/lib/dwb/sbjl 
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/usr/lib/dwb/sbj2 

/usr/lib/dwb/sbj3 

/usr / lib / d wb /sb jprep 

/usr/iib/dwb/stylel 

/usr/lib/dwb/slyle2 

/usr/lib/dwb/style3 

/usr/lib/eign 

/usr/lib/macros/an 

/ usr/lib/ macros/mmn 

/usr/lib/macros/mmt 

/ usr/lib/ macros/ ptx 

/usr/lib/macros/strings.mm 

/ usr / lib / macros / vmca 

/ usr / lib / tmac/ tmac.an 

/usr/lib/ tmac/tmac.m 

/usr/lib / tmac / tmac.p tx 

/usr/lib/ tmac/tmac.v 

The fourth diskette contains the driver, font tables, and raster tables for 
the Imagen IMPRINT-10 laser printer. The files contained on this diskette 
require 2350 blocks of free space in the /usr file system. This disk is to be 
used with troff and contains the following files: 



/usr/bin/dilO 

/usr/lib/font/devilO/B.out 

/usr/Iib/fonl/devilO/CW.out 

/usr/lib/font/devilO/DESCoul 

/usr/lib/font/devilO/H.out 

/usr/lib/font/devilO/HI.out 

/usr/lib/font/devilO/HK.out 

/usr/lib/font/devilO/I.out 

/usr/lib/font/devilO/PA.out 

/usr/lib/font/devilO/PB.out 

/usr/lib/font/devilO/Pl.out 

/usr/lib/fonl/devilO/PO.out 

/usr/lib/font/devilO/R.out 

/usr/lib/font/devilO/S.out 

/usr/lib/font/devilO/rastilO/B.lO 

/usr/lib/font/devilO/rastilO/B.12 

/usr/lib/font/devilO/rastilO/B.14 

/usr/lib/font/devilO/rastilO/B.16 

/usr/lib/font/devilO/raslilO/B,6 
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/usr/Iib/font/devilO/rastilO/B.8 

/usr/lib/font/devilO/rastilO/B.9 

/usr/lib/font/devilO/rastilO/BLlO 

/usr/lib/font/devilO/rastilO/BL12 

/usr/lib/font/devilO/rastilO/BL6 

/usr/lib/font/devilO/rastilO/BI.8 

/usr/lib/font/devilO/rastilO/CW.lO 

/usr/lib/font/devilO/rastilO/CW.ll 

/usr/lib/font/devilO/rastilO/CW.12 

/usr/lib/font/devilO/rastilO/CW.16 

/usr/lib/font/devilO/rastilO/CW.6 

/usr/lib/font/devilO/rastilO/CW.8 

/usr/lib/font/devilO/rastilO/CW.9 

/usr/lib/font/devilO/rastilO/H.lO 

/usr/lib/font/devilO/rastilO/H.12 

/usr/lib/font/devilO/rastilO/H.14 

/usr/lib/font/devilO/rastilO/H.16 

/usr/lib/font/devilO/rastilO/H.18 

/usr/lib/font/devilO/rastilO/H.6 

/usr/lib/font/devilO/rastilO/H.8 

/usr/lib/font/devilO/rastilO/H.9 

/usr/lib/font/devilO/rastilO/HB.lO 

/usr/lib/font/devilO/rastilO/HB.14 

/usr/lib/font/devilO/rastilO/HB.9 

/usr/lib/font/devilO/rastilO/HI.lO 

/usr/lib/font/devilO/rastilO/HL12 

/usr/lib/font/devilO/rastilO/HL14 

/usr/lib/£ont/devilO/rastilO/HL16 

/usr/lib/font/devilO/rastilO/HL18 

/usr/lib/font/devilO/rastilO/HL6 

/usr/lib/font/devilO/rastilO/HI.8 

/usr/lib/font/devilO/rastilO/HI.9 

/usr/lib/font/devilO/rastilO/HK.lO 

/usr/lib/font/devilO/rastilO/HK.12 

/usr/lib/font/devilO/rastilO/HK.14 

/usr/lib/font/devilO/rastilO/HK.16 

/usr/lib/font/devilO/rastilO/HK.18 

/usr/lib/font/devilO/rastilO/HK.6 

/usr/lib/font/devilO/rastilO/HK.8 

/usr/lib/font/devilO/rastilO/HK.9 

/usr/lib/font/devilO/rastilO/I.lO 
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/usr/lib/font/devilO/rastilO/S.12 

/usr/lib/font/devilO/rastilO/S.14 

/usr/lib/font/devilO/rastilO/S.16 

/usr/lib/font/devilO/rastilO/S.18 

/usr/lib/font/devilO/rastilO/S.24 

/usr/lib/font/devilO/rastilO/S.6 

/usr/lib/font/devilO/rastilO/S.8 

/usr/lib/foiit/devilO/rastilO/S.9 

/usr/lib/font/devilO/rastilO/devaps/B.out 

/usr/lib/font/devilO/rastilO/devaps/BI.out 

/ usr / lib / font / de vilO/ rastilO / devaps/ C.out 

/usr/lib/font/devilO/rastilO/devaps/CEout 

/usr/lib/font/devilO/rastilO/devaps/CLout 

/usr/lib/font/devilO/rastilO/devaps/CT.out 

/usr/lib/font/devilO/rastilO/devaps/CW.out 

/usr/lib/font/devilO/rastilO/devaps/DESC.out 

/usr / lib / font / de vilO/ rastilO / devaps / G.out 

/usr/lib/font/devilO/rastilO/devaps/GB.out 

/usr/lib/font/devilO/rastilO/devaps/GI.out 

/usr/lib/font/devilO/rastilO/devaps/GR.out 

/usr/lib/font/devilO/rastilO/devaps/GS.out 

/usr/lib/font/devilO/rastilO/devaps/H.out 

/usr/lib/font/devilO/ra5tilO/devap5/HB.out 

/usr/lib/font/devilO/rastilO/devaps/HLout 

/usr/lib/font/devilO/rastilO/devaps/I.out 

/usr/lib/font/devilO/rastilO/devaps/MB.out 

/usr/lib/font/devilO/rastilO/devaps/MI.out 

/usr/lib/font/devilO/rastilO/devaps/MR.out 

/usr/lib/font/devilO/rastilO/devaps/MX.out 

/usr/lib/font/devilO/rastilO/devaps/PA.out 

/usr/lib/font/devilO/rastilO/devaps/PB.out 

/usr/lib/font/devilO/rastilO/devaps/PI.out 

/usr/lib/font/devilO/rastilO/devaps/PO.out 

/usr/lib/font/devilO/rastilO/devaps/R.out 

/usr/lib/font/devilO/rastilO/devaps/S.out 

/usr/lib/font/devilO/rastilO/devaps/Sl.out 

/usr/lib/font/devilO/rastilO/devaps/SCout 

/usr/lib/font/devilO/rastilO/devaps/SM.out 

/usr/lib/font/devilO/rastilO/devaps/TB^out 
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Installation Procedure 

This section guides you through the installation procedure for 
DOCUMENTER'S WORKBENCH Software on the 3B2 Computer using the 
installpkg command found in the System Administration Menus system, 
(Type sysadm to invoke the menu.) 

The installpkg command prints its instructions very quickly. Always 
read the instructions carefully before you do anything. For example, the 
system can "hang" if you press < RETURN > before you insert a diskette in 
the floppy drive. 



NOfTE 

"T" 



If this happens, 1) Press the break key. 2) Insert the diskette into the 
floppy drive. 3) Press <CR>. 4) Start the instructions over. If this does 
not help, rebooting the system is the only recovery. 



Use the standard software installation procedure described in your 3B2 Com- 
puter Owner! Operator Manual, 



Removing DOCUMENTER'S WORKBENCH Software 
from the 3B2 Computer 

Use the standard software removal procedure described in your 3B2 
Computer Owner I Operator ManuaL 
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Documents for the DOCUMENTER'S WORK- 
BENCH Software 



Six documents are available, including this document, which provide all 
the information needed to successfully use the DOCUMENTER'S WORK- 
BENCH Software. 

These documents are as follows: 

■ DOCUMENTER'S WORKBENCH Software Release Notes 
(Select Code 310-007) 

■ DOCUMENTER'S WORKBENCH Software Hartdbook for New Users 
(Select Code 310-009) 

■ DOCUMENTER'S WORKBENCH Software Handbook 
(Select Code 310-008) 

■ DOCUMENTER'S WORKBENCH Software Product Overview 
(Select Code 310-006) 

■ DOCUMENTER'S WORKBENCH Software User's Guide 
(Select Code 310-004) 

■ DOCUMENTER'S WORKBENCH Software Technical Discussion and 
Reference Manual 

(Select Code 310-005) 
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Warnings 



An inapplicable error message may appear when the source package for 
DOCUMENTER'S WORKBENCH Software is installed on 3B20 Computers run- 
ning early releases of UNIX System V, such as SVR2.0 Version 2. The mes- 
sage 




*»*« error oode 1 (ignored) 




should be ignored. Building of the source package will in no way be 
affected. 

The terminal description files for nroff /troff contained in 
usr/lib/nterm have been converted from compiled C language object code 
to ASCII files in this release. If you have written any terminal description 
files of your own, you will need to convert them to ASCII format (see 
Appendix 4). 
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Upgrading Release 1.0 to Release 2.0 



This section provides information on preserving commands and source 
for components that have been discontinued for DOCUMENTER'S WORK- 
BENCH Software Release 2.0. Given below for each feature is a brief 
description as well as the location of the source code and the object code. 
Discontinued features are no longer supported. 



Changes 

DOCUMENTER'S WORKBENCH Software Release 2.0 has a new directory 
structure. The substructure under /usr/src/cmd/text/troff.d in 
DOCUMENTER'S WORKBENCH Release 1.0 has been moved to 
/usr/src/cmd/text/roff.d/troff.d in DOCUMENTER'S WORKBENCH Software 
Release 2.0 where it cohabits with the new nroff . Therefore, any local or 
discontinued software that existed under /usr/src/cmd/text/troff.d should 
be moved to a corresponding position under 

/usr/src/cmd/text/roff.d/troff.d. DOCUMENTER'S WORKBENCH Software 
Release 2.0 overwrites roff.d where otroff resided in DOCUMENTER'S WORK- 
BENCH Release 1.0. To preserve otroff, the old roff.d/* and 
roff.d /fonts.d/* should be moved to a new name (for example, Oroff.d). 
All makefiles have to be modified to make the components that have been 
discontinued. 

The following DOCUMENTER'S WORKBENCH Software Release 1.0 
features are not included in DOCUMENTER'S WORKBENCH Software Release 
2.0, and are no longer supported: 

checkcw: checkcw is used with ocw. Since otroff will not be dis- 



tributed with DOCUMENTER'S WORKBENCH Software 
Release 2.0, there is no longer any need for checkcw. 
checkcw checks that left and right delimiters, as well as 
the .CW/.CN pairs, are properly balanced. 



checkeq: 



checkeq was used with eqn. The command checkmm 
provides more extensive checking of proper equation for- 
matting. 



dx9700: 



dx9700 prepares troff documents for the Xerox 9700 
printer. The command will not be distributed with 
DOCUMENTER'S WORKBENCH Software Release 2.0. 
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Upgrading from Release 1.0 



mmlint: 



non-btl.sh: 



ocw: 



osdd: 



otc: 



otroff: 



sroH: 



X9700: 



mmlint is an sro£f/mm nroff/mm document compatibil- 
ity checker. Since sroff/mm will not be distributed with 
DOCUMENTER'S WORKBENCH Software Release 2.0, there 
is no longer a need for mmlint. 

non-btLsh reinstalls mm macros without AT&T Bell 
Laboratories specific features. This does not have to be 
saved since AT&T Bell Laboratories specific strings have 
been moved to a file external to the mm macro package 
called strings.mm. strings.mm can be modified by the 
system administrator to meet specific needs. (See the fol- 
lowing section, "Defining Memo Headings with 
strings.mm.") 

ocw is a preprocessor for otroff. Since otroff will not be 
distributed with DOCUMENTER'S WORKBENCH Software 
Release 2.0, there is no longer any need for ocw. 

The OSDD adapter macro package is a tool used in con- 
junction with the mm macro package to prepare Opera- 
tions Systems Deliverable Documentation. The command 
will not be distributed with DOCUMENTER'S WORK- 
BENCH Software Release 2.0. 

otc is a postprocessor for otroff. Since otroff will not be 
distributed with DOCUMENTER'S WORKBENCH Software 
Release 2.0, there is no longer any need for otc. 

The otroff text formatter is an early version of troff that 
formats text for only one device, the C/A/T photo- 
typesetter, otroff will not be distributed with 
DOCUMENTER'S WORKBENCH Software Release 2.0. 

sroff and its mm macro package formats text for printing 
on typewriter-like devices and line printers, including 
the Xerox 9700 printer, sroff will not be distributed with 
DOCUMENTER'S WORKBENCH Software Release 2.0. 

x9700 prepares nroff documents for the Xerox 9700 
pointer. The command x9700 will not be distributed with 
DOCUMENTER'S WORKBENCH Software Release 2.0. 
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upgrading from Release 1.0 



The following table represents what directories and /or files should be 
saved to preserve source and object code for discontinued components. All 
source directories are relative to /usr/src/cmd/text. 



Command / Component 


Source 


Object or Library Files 


checkcw 


old.d/checkcw.c 


/ usr / bin / checkcw 


dx9700 


troff.d/devX97 

troff.d/devX97/X97.timl0p 

troff.d/devX97/X97.liml2p 


/usr/bin/dx9700 

/usr/lib/font/devX97.timl0p/* 

/usr/Iib/font/devX97.timl2p/* 


mmlint 


mmlint.d 


/usr/bin/mmlint 


ocw 


old.d/ocw.c 


/usr/bin/ocw 


osdd 


shell$.d/osdd.sh 
macros.d / osdd.src 
macros.d / 1 mac.osd 


/usr/bin/osdd 
/usr/lib/tmac/tmac.osd 
/usr/lib/ macros/osdd 


otc 


old.d/otc.c 


/usr/bin/otc 


otroff 


roff.d roff.d/fonts.d 


/usr/ bin /otroff 
/usr/lib/fonts/* 


sroff 


sroff.d 


/usr/bin/sroff 


sroff/mm 


sroff.d 


/usr/ lib /macros /sroff .mm 


X9700 


x9700.d 


/usr/bin/x9700 



Defining Memo Headings with strings.mm 

The file strings.mm is external to and supplements the mm macro pack- 
age. The file contains 26 string definitions enabling the user to specify a 
company's name, logo, and proprietary information to appear on memos 
written with the formal memorandum macros. The following is a list of 
those string definitions: 
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.ds]S 
.ds}Z 
.ds]M 
.ds]0 
.ds]Q 
.ds]R 
.ds]A 
.ds]F 
.ds]G 
.ds]H 
.ds]I 
.ds]J 
.dslK 
.ds]L 
.ds]U 
.ds]V 
.ds]W 
.ds]X 
.ds]i 
.ds]j 
.cls]k 
.dsU 
.dslm 
.ds]o 
.ds]p 
.ds]q 



1 string definition for company's logo 
1 string definition for company's name 



string definitions for company's proprietary markings 



string definitions for company's proprietary markings 



string definitions for company's proprietary markings 



string definitions for company's proprietary markings 



string definitions for company's proprietary markings 



string definitions for company's proprietary markings 



You will notice that there is room for one definition of a company's 
logo and one for a company's name. There are 6 sets of definitions for 
proprietary markings, however, each set containing 4 definitions. This 
variety of definitions for proprietary markings is to allow for the different 
levels of security due to different documents. Each set is allowed four lines 
since most markings require several lines to state their specific levels of sen- 
sitivity. The first set (]M-pl) corresponds to the macro .PM PMl. The second 
set (]A-]H) corresponds to the macro .PM PM2. The third set (p-JL) 
corresponds to the macro .PM PM3. The fourth set (JU-pC) corresponds to the 
macro .PM PM4. The fifth set (p-JI) corresponds to the macro .PM PM5. The 
sixth set (]m-]q) corresponds to the macro .PM PM6. A sample proprietary 
marking might look like this: 
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.ds]U AT&T BELL LABORATORIES - PROPRIETARY (RESTRiCTED) 
.ds]V Solely for authorized persons having a need to know 
.dsjW pursuant to G.E.L 2.2 
.Gls]X 





Thus, each time you used the macro .PM PM4, the three lines given above 
would appear, centered, at the bottom of each page. 

The formal memorandum macros will not allow both definitions at ]S 
and )Z to appear together. If the logo is defined at p, the company name at 
)Z will be ignored. If the logo is not defined, the memo will give the com- 
pany name only for its letterhead. Should you want both logo and name to 
appear together, define both at JS. nroff will format whatever it is capable 
of formatting; if a logo is defined at JS that only a typesetter can process, it 
will not appear in an nroffed memo's letterhead. 
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Appendix 1: Source Files 



The DOCUMENTER'S WORKBENCH Software Release 2.0 source product 



contains the following files: 


/usfi 


^src/cmd/ 


^text/ 


1 checkmm.d/checkmm.mk 


/usri 


^src/cmdj 


^texti 


(checkmm.d/chekLl 


/usri 


^src/cmdi 


^texti 


fcheckmm.d/chekll.l 


/usr/ 


^src/cmdi 


^texti 


(checkmm.d/chekmain.c 


/usri 


^src/cmdi 


ftexii 


f checkmm.d/chekmainl.c 


/usri 


^src/cmdi 


ftexti 


1 checkmm.d/chekrout.c 


/usri 


^src/cmdy 


fiexti 


f checkmm.d/chekroutl.c 


/usri 


^src/cmdj 


^texti 


f eqn.d / apseqnchar 


/usri 


^src/cmdj 


'text/ 


^eqn.d/cateqnchar 


/usri 


^src/cmdj 


^texti 


^eqn.d/diacrit.c 


/usri 


^src/cmdi 


^texti 


feqn.d/e.h 


/usr/ 


^src/cmdi 


^texti 


feqn.d/e.y 


/usr/ 


^src/cmdj 


^texti 


feqn.d/eqn.mk 


/usri 


^src/cmdi 


^texti 


f eqn.d /eqnbox^c 


/usri 


^src/cmdi 


^texti 


(eqn.d/fontc 


/usri 


^src/cmd^ 


'texti 


(eqn.d/fromto.c 


/usri 


^src/cmdi 


'texti 


feqn.d/funny.c 


/usri 


^src/cmd^ 


ftexii 


f eqn.d /glob.c 


/usri 


^src/cmdi 


ftexii 


feqn.d/integral.c 


/usri 


^src/cmdi 


ftexii 


feqn.d/io.c 


/usri 


^src/cmdi 


Itexti 


feqn.d/lex.c 


/usri 


^src/cmdi 


^texli 


^eqn.d/lookup.c 


/usri 


^src/cmdj 


'texti 


feqn.d/mainx 


/usri 


fsTc/cmdi 


'texti 


^eqn.d/mark.c 


/usri 


fstc/cmdi 


^texti 


f eqn.d/ ma trix.c 


/usri 


^src/cmdi 


^texti 


feqn.d/move.c 


/usri 


^src/cmdi 


^texli 


f eqn.d /over.c 


/usri 


^src/cmd) 


^texti 


feqn.d/paren.c 


/usri 


^src/cmdi 


^texti 


(eqn.d/pile.c 


/usri 


^src/cmdi 


^texti 


feqn.d/shift.c 


/usri 


^src/cmdi 


^texti 


feqn.d/size.c 


/usri 


^src/cmdj 


^texti 


feqn.d/sqrtc 


/usri 


fsrc/cmdi 


^texti 


f eqn.d /textc 


/usri 


^src/cmdi 


^texti 


fdiffmk.sh 


/usri 


^src/cmdi 


^texti 


fgrap.d/README 


/usri 


^src/cmdi 


^texti 


fgrap.d/coord.c 
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/ usr / src / cmd / tex t / grap.d / f or.c 

/ usr /src / cmd / tex t / grap.d / framex 

I usr / src / cmd / text / grap.d / grap.defines 

/ usr / src / cmd / tex t / grap.d / grap.h 

/ usr / src / cmd / text / grap.d / grap.mk 

/usr/src/cmd/text/grap.d/grap.y 

/ usr / src / cmd / tex t / grap.d /grapl.l 

/usr/src/cmd/text/grap.d/input.c 

/ usr / src / cmd / tex t / grap.d / label.c 

/ usr / src / cmd / text / grap.d / main.c 

/ usr / src / cmd / tex t / grap.d / misc.c 

/ usr / src / cmd / text /grap.d / plot .c 

/ usr / src / cmd / text / grap.d / prin t.c 

/ usr / src / cmd / tex t / grap.d / ticks.c 

/ usr / src / cmd / text / macref .d / macref .c 

/ usr / src / cmd / text / macref .d / macref .mk 

/ usr / src / cmd / tex t / macref .d / macrf orm.c 

/usr/src/cmd/text/macref.d/macrstat.c 

/ usr / src / cmd / tex t / macref .d / macr toc.c 

/ usr /src / cmd / text / macref .d / main.c 

/usr/src/cmd/text/macref.d/match.c 

/ usr /src / cmd / text / hyphen.c 

/usr/src/cmd/text/macros.d/an.src 

/usr/src/cmd/text/macros.d/macros.mk 

/ usr / src / cmd / text / macros.d / macrunch 

/ usr /src / cmd / text / macros.d / mmn.src 

/ usr / src / cmd / text / macros.d / mm t. src 

/ usr / src / cmd / tex t / macros.d / 1 macan 

/ usr / src / cmd / tex t / macros.d / tmac.m 

/ usr / src / cmd / tex t / macros.d / p tx.src 

/usr /src / cmd / text / macros.d /strings.mm.src 

/ usr / src / cmd / tex t / macros.d / 1 mac.ptx 

/ usr / src / cmd / text / macros.d / 1 mac. v 

/ usr / src / cmd / tex t / macros.d / vmca.src 

/ usr /src / cmd / text / neqn.d / diacrit.c 

/ usr / src / cmd / text /neqn.d/e.h 

/usr/src/cmd/text/neqn.d/e.y 

/ usr /src / cmd / text / neqn.d / eqnbox.c 

/usr/src/cmd/text/neqn.d/font.c 

/ usr / src / cmd / text / neqn.d / f rom to.c 

/usr/src/cmd/text/neqn.d/funny.c 
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/usr/src/cmd/text/neqn.d/glob.c 

/usr/src/cmd/text/neqn.d/integral.c 

/ usr / src / cmd / text / neqn.d / io.c 

/usr/src/cmd/text/neqn.d/lex.c 

/ usr / src / cmd / text / neqn.d / lookups 

/usr/src/cmd/text/neqn.d/mark.c 

/usr/src/cmd/text/neqn.d/matrix.c 

/ usr/src/cmd/text/neqn«d/move.c 

/ usr / src / cmd / text / neqn.d / neqn.mk 

/ usr/ src/ cmd/ text /neqn.d/over.c 

/ usr / src / cmd / text / neqn.d / paren.c 

/ usr /src / cmd / text / neqn.d / pile.c 

/usr/src/cmd/text/neqn.d/shiftc 

/usr/src/cmd/text/neqn.d/size.c 

/usr/src/cmd/text/neqn.d/sqrtc 

/ usr / src / cmd / text / neqn.d / textc 

/usr/src/cmd/text/pic.d/PS-PEmacros 

/usr/src/cmd/text/picd/README 

/usr/src/cmd/text/pic.d/arcgen.c 

/ usr/src/ cmd /text/ pied /blockgen.c 

/usr/src/cmd/text/pic.d/boxgen.c 

/ usr/src /cmd /text/ pied /circgen.c 

/ usr/src/ cmd /text/ pied /for.c 

/usr/src/cmd/text/pic.d/input.c 

/usr/src/cmd/text/pic.d/linegen.c 

/ usr/src/cmd/text/picd/main.c 

/ usr/ src / cmd / text / pied / misc.c 

/ usr/ src / cmd / text / pied / mo vegen.c 

/ usr/ src/cmd/text/pic.d/pic.h 

/usr/src/cmd/text/pic.d/pic.mk 

/ usr / src / cmd / text / pied /picl.1 

/ usr / src/ cmd / text / pied / picy .y 

/usr/src/cmd/ text/pied /pltroff.c 

/ usr/ src / cmd / text / pied / print.c 

/usr/src/cmd/text/pied/symtab.c 

/ usr/ src / cmd / text / pied / textgen.c 

/usr/src/cmd / text /p tx.d / eign.sh 

/usr/src/cmd/text/ptx.d/ptx.c 

/usr/src / cmd / text / p tx.d / p tx.mk 

/usr/src/cmd/text/ro£f.d/nroff.d/terms.d/README 

/ usr / src / cmd / text / roff.d / nroff .d / terms.d /a.2631 
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/ usr / src / cmd / text / roff .d / nroff .d 
/ usr / src / cmd / text / roff .d / nroff .d 
/ usr / src / cmd / text / roff .d / nroff .d 
/ usr/ src / cmd / text / roff .d / nroff .d 
/ usr /src / cmd / text / roff .d / nroff .d 
/ usr / src / cmd / text / roff .d / nroff .d 
/ usr / src / cmd / text / roff .d / nroff .d 
/ usr /src/ cmd / text / roff .d / nroff .d 
/ usr/ src / cmd / text / roff *d / nroff .d 
/usr/src/cmd/text/roff*d/nroff.d 
/ usr /src / cmd / text / roff .d / nroff .d 
/ usr /src / cmd / text / roff .d / nroff .d 
/ usr / src / cmd / text / roff .d / nroff «d 
/ usr/ src / cmd / text / roff .d / nroff .d 
/ usr / src / cmd / text I toff A I nroff .d 
/ usr / src / cmd / text I toff. A I nroff .d 
/usr /src/ cmd/ text/ roff .d/ nroff .d 
/ usr / src / cmd / text / roff .d / nroff .d 
/ usr/src / cmd / text / roff .d / nroff .d 
/ usr / src / cmd / text / roff .d / nroff .d 
/usr/src/cmd/text/roff.d/nroff.d 
/ usr/src / cmd / text / roff .d / nroff .d 
/ usr /src / cmd / text / roff .d / nroff .d 
/ usr / src / cmd / text / ro ff.d / nroff .d 
/usr/src/cmd/text/roff.d/nroff.d 
/usr /src/ cmd / text / roff .d /ext.h 
/ usr / src / cmd / text / roff .d / hy tab.c 
/ usr/src / cmd / text / roff .d / nl.c 
/usr/src / cmd / text / roff .d / n2.c 
/usr/src/cmd/text/roff.d/n3.c 
/ usr/src / cmd / text / roff *d / n4.c 
/ usr/ src /cmd /text/ roff .d/n5.c 
/ usr/src / cmd / text / roff .d / n7.c 
/ usr/src / cmd / text / roff .d / nS.c 
/ usr / src / cmd / text / roff .d / n9.c 
/usr/src/cmd/text/roff.d/ni.c 
/usr/src/cmd/text/roff.d/nii.c 

/ usr / src / cmd / text I toff A I troff .d / devaps / charlib / LH.36 
/ usr / src / cmd / text / roff .d / troff .d / devaps / charlib / L V.36 
/usr/src/cmd/text/roff.d/troff.d/devaps/charlib/README 
/ usr / src / cmd / text / roff .d / 1 roff .d / devaps / B 



terms.d/a.2631-c 

terms.d/a.2631-e 

terms.d/a.300 

terms.d/a300-12 

terms.d/a.300s 

terms.d/a.300s-12 

terms.d/a.382 

terms.d/a.4000a 

terms.d/a.450 

terms.d/a.450-12 

terms.d/a.832 

terms.d/a.lp 

terms.d/ab.37 

terms.d/ab.8510 

terms.d/ab.X 

terms.d/ab.tn300 

terms.d/b.300 

terms.d/b.lp 

terms.d/convert.sh 

terms.d / template 

terms.d / terms.mk 

nlO,c 

n6.c 

nroff.mk 
tw,h 
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/usr/src/cmd/text/ro£f.d/troff.d/devaps/BI 

/usr/src/cmd/text/rof(.d/troff.d/devap5/C 

/usr/src/cmd/text/roff.d/troff.d/devaps/CE 

/usr/src/cmd/text/ro£(.d/trof(.d/devaps/CI 

/usr/src/cmd/text/roff.d/trof^.d/devaps/CT 

/usr/src/cmd/text/ro{(.d/tro£(.d/devaps/CW 

/usr/src/cmd/text/ro£f.d/troff.d/devaps/CX 

/usr/src/cmd/text/ro£f.d/troff.d/devaps/DESC 

/ usr /src / cmd / text / toff .d / troff .d / de vaps / G 

/usr/src/cind/text/ro£f.d/trof£.d/devap5/GB 

/usr/src/cmd/text/roff.d/trotf.d/devaps/GI 

/usr/src/cmd/text/roff.d/troff.d/devaps/GR 

/usr/src/cmd/text/roff.d/troff.d/devaps/GS 

/ usr/ src / cmd / text / roff .d / troff .d / de vaps / H 

/ usr/ src / cmd /text/ roff .d/ troff .d/devaps/HB 

/ usr/ src / cmd / text / roff .d / troff .d / de vaps/ HI 

/u^r/src/cmd/text/roff.d/troff.d/devaps/HK 

/ usr/ src /cmd / text / roff .d / troff .d / de vaps / HL 

/usr/src/cmd/text/roff.d/troff.d/devaps/HX 

/usr/src/cmd/ text/ roff .d/troff .d/devaps/I 

/usr/src/cmd/text/roff.d/troff.d/devaps/LINKFILE 

/ usr / src / cmd / text / roff .d / troff .d / de vaps / MB 

/ usr/src/cmd /text/ roff.d/ troff .d/de vaps /MI 

/ usr / src / cmd / text / roff .d / troff .d / de vaps /MR 

/usr/src/cmd/text/roff.d/troff.d/devaps/MX 

/ usr / src / cmd / text / roff .d / troff .d / de vaps / PA 

/ usr / src / cmd / text / roff .d / troff .d / de vaps / PB 

/ usr / src / cmd / text / roff .d / troff .d / de vaps / PI 

/usr/src/cmd / text / roff .d / troff .d / de vaps / PO 

/ usr /src / cmd / text / roff .d / troff .d / de vaps / PX 

/ usr /src / cmd / text / roff .d / troff .d / de vaps / R 

/usr/src/cmd/text/roff.d/troff.d/devaps/README 

/ usr /src / cmd / text / roff .d / troff .d / de vaps / S 

/usr/src/cmd/text/roff.d/troff.d/devaps/Sl 

/usr/src/cmd/text/roff.d/troff.d/devaps/SC 

/ usr /src / cmd / text / roff .d / troff .d / de vaps / SM 

/usr/src/cmd/text/roff.d/troff.d/devaps/TB 

/usr/src/cmd / text / roff .d / troff .d / de vaps / TX 

/ usr /src / cmd / text / roff .d / troff .d / de vaps / aps.h 

/usr/src/cmd/text/roff.d/troff.d/devaps/build.c 

/ usr /src / cmd / text / roff «d / 1 roff .d / de vaps / daps.c 
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/usr /src / cmd / text / roff .d / tr off .d / de vaps / daps.g 

/ usr /src / cmd / text / roff .d / troff .d / de vaps / daps.h 

/usr/src/cmd/text/roff.d/troff.d/devaps/devaps.ink 

/usr/src/cmd/text/roff.d/troff.d/devaps/makedev.c 

/usr /src / cmd / text / roff .d / troff .d / de vaps / version 

/usr/src/cmd/text/roff.d/troff.d/README 

/ usr / src / cmd / text / roff .d / troff .d / de v.h 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/B 

/usr/src/cmd/text/roff*d/troff.d/devilO/rastilO/aps-ilO/B,S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/B.bld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/BI 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/BI.S 

/usr/src/cird/text/roff.d/troff-d/devilO/rastilO/aps-ilO/BLbld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/C 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/CS 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/Cbld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/CE 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/CE.S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/CE.bld 

/usr/src/cmd/text/roff.d/troff,d/devilO/rastilO/aps-ilO/CI 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/CLS 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/CLbld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/CT 

/usr/src/cmd/text/roff.d/lroff.d/devilO/rastilO/aps-ilO/CT,S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/CW 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/DESC 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/FONTMAP 

/usr/src/cmd/text/roff,d/troff.d/devilO/rastilO/aps-ilO/G 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/G.S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/G.bld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/GB 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/GB,S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/GI 

/usr/src/cmd/text/roff.d/troff-d/devilO/rastilO/aps-ilO/GLS 

/usr/src/cmd/text/roff.d/troff-d/devilO/rastilO/aps-ilO/GLbld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/GR 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/GR.R 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/GS 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/GS.S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/H 

/usr/src/cmd/text/roff-d/troff.d/devilO/rastilO/aps-ilO/H.S 
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/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/H.bld 

/usr/src/cmd/text/roff.d/troff,d/devilO/rastilO/aps-ilO/HB 

/usr/src/cmd/text/roff.d/tro£f,d/devilO/rastilO/aps-ilO/HB.S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/HB.bld 

/usr/src/cmd/text/ro£f.d/troff,d/devilO/rastilO/aps-ilO/HI 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/HLS 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/HLbld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/I 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/I.S 

/usr/src/cmd/texl/roff.d/troff.d/devilO/rastilO/aps-ilO/I.bld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/LINKFILE 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/MB 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/MB.S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/MB.bld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/MI 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/MLS 

/usr/src/cmd/text/roff.d/tro£f,d/devilO/rastilO/aps-ilO/MLbld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/MR 

/usr/src/cmd/texl/roff.d/troff.d/devilO/rastilO/aps-ilO/MR.S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/MR.bld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/MX 

/usr/src/cnid/text/roff.d/troff.d/devilO/rastilO/aps-ilO/MX.S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/MX.bld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/PA 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/PA.S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/PA.bld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/PB 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/PB,S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/PB.bld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/PI 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/PLS 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/PI.bld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/PO 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/R 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/rastilO/aps-ilO/R.S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/R.bld 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/README 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/S 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/S.R 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/Sl 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/SC 
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/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/ap8-ilO/SCS 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/aps-ilO/SM 

/usr/$rc/cmd/text/rof£.d/troff.d/devilO/rastilO/aps-ilO/SM.S 

/usr/src/cmd/text/ro£f.d/troff.d/devilO/rastilO/aps-ilO/TB 

/usr/src/cind/text/ro£f.d/tro£f.d/devilO/rastilO/aps-ilO/TB.S 

/usr/src/cind/text/ro£f.d/tro£f.d/devilO/rastilO/aps-ilO/TB.bld 

/usr/src/cmd/text/ro£f.d/troff.d/devilO/rastilO/aps-ilO/aps-il0.mk 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/RASTERDEV 

/usr/src/cmd/text/ro£f-d/troff-d/devilO/rastilO/RASTERLIST 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/rastilO/README 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/fbuild.c 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/fdump.c 

/usr/src/cmd/text/roff.d/troff.d/devil0/rastil0/inake3brastc 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/rastilO.mk 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/B.10 

/usr/src/cmd/text/ro£f.d/troff-d/devilO/rastilO/B,12 

/usr/src/cmd/text/roff.d/trof£-d/devilO/rastilO/B.14 

/usr/src/cmd/text/ro£f-d/tro£f.d/devilO/rastilO/B.16 

/usr/src/cind/text/roff.d/troff.d/devilO/rastilO/B.6 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/B.8 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/B.9 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/BI.10 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/BL12 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/BL6 

/usr/src/cmd/text/roff,d/troff.d/devilO/rastilO/BL8 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/CW.lO 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/CW.ll 

/usr/src/cmd/text/ro£f.d/troff.d/devilO/rastilO/CW.12 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/CW.16 

/usr/src/cmd/text/roff,d/troff-d/devilO/rastilO/CW.6 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/CW.S 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/raslilO/CW.9 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/H.lO 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/H.12 

/usr/src/cmd/text/roff.d/troff*d/devilO/rastilO/H.14 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/H.16 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/H.18 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/H.6 

/usr/src/cmd / text / roff .d / troff .d /devilO/ rastilO/ H.8 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/H.9 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/HB.lO 
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/usr/src/cind/text/roff.d/troff.d/devilO/rastilO/HB.14 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/HB.9 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/HL10 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/HL12 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/HL14 

/usr/src/cind/text/ro£f.d/tro£f-d/devilO/rastilO/HL16 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/HL18 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/HL6 

/usr/src/cmd/text/roff.d/tro£f,d/devilO/rastilO/HL8 

/usr/src/cmd/text/ro£f.d/troff.d/devilO/rastilO/HL9 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/HK.10 

/usr/src/cind/text/ro£f.d/tro£f.d/devilO/rastilO/HK.12 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/HK.14 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/HK.16 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/HK.18 

/usr/src/cmd/text/ro£f.d/tro£f,d/devilO/rastilO/HK.6 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/HK.8 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/rastilO/HK.9 

/usr/src/cmd/text/ro£f.d/troff.d/devilO/rastilO/L10 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/L12 

/usr/src/cmd/text/ro£f,d/tro£f.d/devilO/rastilO/L14 

/usr/src/cind/text/ro£f.d/tro£f,d/devilO/rastilO/L16 

/usr/src/cmd/text/ro£f.d/troff.d/devilO/rastilO/L6 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/L8 

/usr/src/cmd/text/ro£f,d/tro£f.d/devilO/rastilO/L9 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/PA.10 

/usr/src/cmd/text/ro£f.d/tro£f-d/devilO/rastilO/PA.12 

/usr/src/cmd/text/ro£f.d/tro£f,d/devilO/rastilO/PA.14 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/PA.6 

/usr/src/cmd/text/ro£f,d/tro£f.d/devilO/rastilO/PA.8 

/usr/src/cmd/text/ro£f.d/tro£f,d/devilO/rastilO/PB.10 

/usr/src/cind/text/roff.d/tro£f.d/devilO/rastilO/PB.12 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/PB.14 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/PB,6 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/PB<8 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rastilO/PL10 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/rastilO/PL12 

/usr/src/cind/text/ro£f.d/tro£f,d/devilO/rastilO/PL14 

/usr/src/cmd/text/roff.d/trotf.d/devilO/rastilO/PI.6 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/PI.8 

/usr/src/cmd/text/ro£f,d/tro£f.d/devil0/rastil0/PO.10 
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/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/PO.ll 

/usr/src/cmd/text/roff.d/tro£f.d/devil0/rastil0/PO.12 

/usr/src/cind/text/roff.d/troff.d/devil0/rastil0/PO.16 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/PO.6 

/usr/src/cmd/text/ro£f.d/troff.d/devil0/ras«10/PO.8 

/usr/src/cmd/text/roff.d/tro£f.d/devil0/rastil0/PO.9 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/PX.10 

/usr/src/cind/text/roff.d/troff.d/devilO/rastilO/PX.12 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/rastilp/PX.6 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/rasJilO/PX.8 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/rastilO/R.10 

/usr/src/cmd/text/roff.d/trotf.d/devilO/rastilO/R.12 

/usr/src/cmd/text/roff.d/troff.d/devilO/ra8tilO/R.14 

/usr/src/cind/text/roff.dhroff,d/devilO/rastilO/R.16 

/usr/src/cind/tcxt/roff.d/troff.d/devilO/rastilO/R.6 

/usr/src/cmd/text/ro£f.d/troff.d/devilO/rastilO/R.8 

/usr/8rc/cmd/text/roff.d/troff.d/devilO/rastilO/R.9 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/rastilO/S.10 

/usr/src/cmd/text/roff.d/boff.d/devilO/rastilO/S.12 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/S.14 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/S.16 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/S.lS 

/usr/src/cind/text/roff.d/trotf.d/devilO/rastilO/S.24 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/S.e 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/S.8 

/usr/src/cmd/text/roff.d/troff.d/devilO/rastilO/S.9 

/usr/src/cmd/text/roff.d/troff.d/devilO/B 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/CW 

/usr/src/cmd/text/roff.d/troff.d/devilO/DESC 

/usr/src/cmd/text/roff.d/troff.d/devilO/FONTCHANGES 

/usr/src/cmd/text/ro£f.d/troff.d/devilO/FONTMAP 

/u8r/src/cmd/text/roff.d/troff.d/devilO/H 

/usr/src/cmd/text/roff.d/troff.d/devilO/HI 

/ usr/src / cmd / text / roff .d / troff .d /devilO/ HK 

/usr/src/cmd/text/roff.d/troff.d/devilO/I 

/usr/src/cmd/text/roff.d/troff.d/devilO/LINKFILE 

/usr/src/cmd/text/roff.d/troff.d/devilO/PA 

/usr/8rc/cmd/text/ro£f.d/tro£f.d/devilO/PB 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/PI 

/usr/src/cmd/text/roff.d/troff.d/devilO/PO 

/usr/src/cmd/text/roff.d/troff.d/devilO/R 
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/usr/src/cmd/text/roff.d/tro£f.d/devilO/RASTi300 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/README 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/S 

/usr/src/cmd/text/roff.d/troff«d/devilO/buildrastc 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/buildrasth 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/devil0.mk 

/usr/src/cmd/text/roff.d/troff.d/devilO/dimpress.c 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/dimpress.h 

/usr/src/cmd/text/rotf.d/trof£.d/devilO/editrast.c 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/editrasth 

/usr/src/cmd/text/ro£f.d/tro£f,d/devilO/exth 

/usr/src/cmd/text/roff.d/troff.d/devilO/gen.h 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/gIob.c 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/glyph.h 

/usr/src/cmd/text/roff.d/tro£f.d/devilO/impcode5.h 

/usr/src/cind/text/roff.d/troff.d/devilO/iinpdraw.c 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/init.h 

/usr/src/cmd/text/rof(.d/troff.d/devilO/makefonts.c 

/usr/src/cmd/text/ro£f.d/tro£f.d/devilO/makeil0.c 

/usr/src/cmd/text/roff.d/troff.d/devilO/miscc 

/usr/src/cmd/text/rof(*d/troff.d/devilO/oldrast.c 

/usr/src/cmd/text/roff.d/troff.d/devilO/printrastx 

/usr/src/cmd/text/roff.d/troff.d/devilO/rast.c 

/usr/src/cmd/text/ro£f,d/tro£f,d/devilO/rasth 

/usr/src/cmd/text/ro£f»d/tro£f.d/devilO/readra8t.c 

/usr/src/cmd/text/roff.d/trof(.d/devilO/spectab.h 

/ usr/src/ cmd/text/roff.d/troff.d/draw.c 

/ usr/ src/cmd / text /roff .d / troff.d/hcc 

/usr/src/cmd/text/ro£f.d/tro£f«d/makedev.c 

/usr/src/cmd/text/roff.d/troff.d/maketables 

/usr/src/cmd/text/ro£f.d/tro£f,d/tlOx 

/usr/src/cmd/text/ro£f.d/tro£f.d/t6.c 

/usr/src/cmd/text/roff.d/troff.d/ta.c 

/usr/src/cmd/text/roff.d/tro£f.d/tc.c 

/usr/src/cmd/text/ro£f,d/tro£f.d/troff.mk 

/usr/src/cmd/text/ro£f.d/troff.d/troff.sh 

/usr/src/cmd/text/roff.d/roff.mk 

/ usr /src/ cmd / text / ro£f .d /suf tab.c 

/usr/src/cmd/text/roff.d/tdef.h 

/usr/src/cmd/text/subndx.d/abbrev.h 

/ usr / src/ cmd / text / subndx.d / case.c 
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/usr/src/cmd/text/subndx.d/cnsth 

/usr/src/cmd/text/subndx.d/conp.h 

/ usr / src / cmd / text /subndx.d / deroff .c 

/usr/src/cmd/text/subndx*d/dict.h 

/usr/src/cmd/text/subndx.d/dstructs.h 

/usr/src/cmd/text/subndx.d/edict.h 

/ usr / src / cmd / text / subndx.d / ehash.h 

/usr/src/cmd/text/subndx.d/end.l 

/ usr /src / cmd / text /subndx.d / extern.c 

/ usr/ src / cmd / text / subndx.d / names.h 

/ usr/ src / cmd / text /subndx.d / ndexer.l 

/usr/src/cmd/text/subndx.d/ndx.sh 

/usr/src/cmd/text/subndx.d/ndxformat.c 

/usr/src/cmd/text/subndx.d/nhash.h 

/ usr / src / cmd / text / subndx.d / n words. 1 

/ usr/ src / cmd / text / subndx.d / omi t.c 

/usr/src/cmd/text/subndx.d/outp.c 

/ usr /src / cmd / text / subndx.d / pages.c 

/usr/src/cmd/text/subndx.d/part.l 

/ usr / src / cmd / text / subndx.d / parts.sh 

/ usr / src / cmd / text / subndx.d / pscan.c 

/ usr / src / cmd / text / subndx.d / roo t wd.c 

/ usr /src / cmd / text /subndx.d / sb|l.l 

/ usr / src / cmd / text /subndx.d / sb j2.1 

/ usr / src / cmd / text / subndx.d / sbj3.1 

/ usr / src / cmd / text /subndx.d / sb jprep.c 

/ usr /src / cmd / text / subndx.d / space.c 

/usr/src/cmd/text/subndx.d/str.c 

/ usr / src / cmd / text /subndx.d / st rr.c 

/usr/src/cmd/text/subndx.d/style.h 

/ usr / src / cmd / text /subndx.d / sub j.sh 

/ usr/ src / cmd / text / subndx.d / subndx.mk 

/usr/src/cmd/text/subndx.d/ydict.h 

/ usr / src / cmd / text / tbl.d / 1 ..c 

/usr/src/cmd/text/tbLd/tO.c 

/usr/src/cmd/text/tbl.d/tl.c 

/ usr /src / cmd / text / tbl.d / t2.c 

/ usr /src / cmd / text / 1 bl.d / t3.c 

/ usr /src / cmd / text / tbl.d / t4.c 

/usr/src/cmd/text/tbl.d/t5.c 

/ usr / src / cmd / text / tbl.d / t6.c 
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/usr/src/cmd/text/tbLd/t7.c 

/usr/src/cmd/text/tbLd/t8.c 

/usr/src/cmd/text/tbLd/t9.c 

/usr/src/cmd/text/tbLd/tb.c 

/usr/src/cmd/text/tbl.d/tbl.mk 

/usr/src/cmd/text/tbl.d/tc.c 

/usr/src/cmd/text/tbl.d/te.c 

/usr/src/cmd/text/tbl.d/tf.c 

/usr/src/cind/text/tbl.d/tg.c 

/usr/src/cmd/text/tbl.d/tLc 

/ usr /src/ cmd / text / tbLd / tm.c 

/usr/src/cmd/text/tbl.d/tr.c 

/usr/src/cmd/text/tbl.d/ts.c 

/ usr / src/ cmd / text / tbLd / tt.c 

/ usr/src/cmd/text/tbLd/tu.c 

/usr/src/cmd/text/tbl.d/tvx 

/ usr /src/ cmd / text /shells.d / eqn.stats 

/usr/src/cmd/text/shells.d/mm.letter 

/usr/src/cmd/text/shells.d/mm.report 

/ udr /src/ cmd / text /shells.d / mm.sales 

/usr/src/cmd/text/shells.d/mm.sh 

/usr/src/cmd/text/shells.d/mmt.sh 

/usr/src/cmd/text/shells.d/nroff.letter 

/usr/src/cmd/text/shells.d/pic.forms 

/usr/src/cmd/text/shells.d/shells.mk 

/usr/src/cmd/text/sheIls.d/tbLbridges 

/usr/src/cmd/text/sheUs.d/tbUanguage 

/ usr /src / cmd / text /shells.d / tbl.pres 

/usr/src/cmd/text/shells.d/terminals 

/usr/src/cmd/text/sheIls.d/troff.ad 

/usr/src/cmd/text/shells.d/troff.aeneid 

/ usr/ src / cmd / text /shells^d / troff .fonts 

/usr/src/cmd/text/shells.d/tro£f .sizes 

/usr/src/cmd/text/text.mk 

/ usr /src / cmd / coLc 
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The eatable manual entries included with all DOCUMENTER'S WORK- 
BENCH Software source products and the 3B5 Computer and the 3B15 Com- 
puter binary products are the following files: 

/ usr / cat man / p_man / manS / eqnchar.5.z 
/ usr / catman / p_man / manS / f ont.5.z 
/ usr / catman / p_man / manS / man.5.z 
/ usr / catman / p_man / manS / mm.S.z 
/ usr / catman / p_man / manS / mp tx.S.z 
/usr/catman/p_man/ man5/mv.5.z 
/ usr / catman / p_man / man5 / nterm.S.z 
/ usr / catman / p__m An / manS / troff .5.z 
/usr/catman/u_man/manl/checkmm.l.z 
/usr / catman / u_man / manl / daps.l.z 
/ usr / catman / u_man / manl / dilO.l.z 
/ usr / catman / u^man / manl / diff mk. 1 .z 
/ usr / catman / u_man / manl / eqn.l.z 
/ usr / cat man / u_man / manl / grap.l.z 
/ usr / catman / ujtnan / manl / hyphen.Lz 
/ usr / catman / u_man / manl / macref .l.z 
/ usr / catman / u_man / manl / mm.l.z 
/usr / catman / u_man / manl / mmt.l.z 
/ usr / catman / ujnan / manl / m vt.l.z 
/ usr / catman / u_man / manl / ndx.Lz 
/ usr / catman / ujnan / manl / neqn.l .z 
/ usr / catman / u_man / manl / nroff .l.z 
/usr / catman / ujman / manl / pic.l.z 
/ usr / catman / u_man / manl / p tx.l.z 
/usr / catman /u_man / manl /sub j.l«z 
/ usr / catman / u_man / manl / tbl. l.z 
/ usr / catman / u_man / manl / tc.l .z 
/usr / catman / u jnan / manl / troff .l.z 

To create your own manual pages for hardcopy or for a local on-line 
facility of eatable manual pages, see DOCUMENTER'S WORKBENCH 
Software Technical Discussion and Reference Manual under the heading 
man(5). 
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To build a local on-line facility, you would use the UNIX system 
commands pack and peat in addition to the appropriate DOCUMENTER'S 
WORKBENCH commands. After processing your pages with nroff (and 
neqn and tbi, if need be), compress the formatted files with pack for 
efficient storage. The resulting directory of local manual pages can be 
displayed on terminal screens using peat. 

troff and its associated preprocessors would be inappropriate for 
building an on-line manual page facility since few terminals are capable 
of displaying troff output. 
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The 3B5 Computer binary product and the 3B15 Computer binary pro- 
duct contain the following executable files: 

/ usr /bin / checkmm 

/usr/bin/checkmml 

/usr/bin/col 

/usr/bin/daps 

/usr/bin/dilO 

/usr/bin/diffmk 

/usr/bin/eqn 

/usr/bin/grap 

/usr/bin/hyphen 

/usr/bin/macref 

/usr/bin/mm 

/usr/bin/mmt 

/usr/bin/mvt 

/usr/bin/ndx 

/usr/bin/neqn 

/usr/bin/nroff 

/usr/bin/pic 

/usr/bin/ptx 

/ usr /bin /sub j 

/usr/bin/tbl 

/usr/ bin /tc 

/usr/bin/troff 

/usr/lib/dwb/deroff 

/ usr / lib / d wb / grap.defines 

/usr/lib/dwb/ndexer 

/ usr / lib / d wb / ndxf orma t 

/usr/lib/dwb/pages 

/ usr / lib / d wb / parts 

/ usr / lib / d wb / samples / eqn.stats 

/usr/lib/dwb/samples/mm.letter 

/usr/lib/dwb/samples/mm.report 

/usr/lib/dwb/samples/mm.sales 

/usr/lib/dwb/samples/nroff.letter 

/ usr / lib / d wb /samples /pic.forms 

/ usr / lib / d wb / samples/ IbLbridges 

/ usr / lib / d wb / samples/ tbLlanguage 
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/usr/lib/dwb/samples/tbLpres 

/ usr/ lib /dwb /samples/ troff. ad 

/usr/lib/dwb/samples/troff.aeneid 

/usr/lib/dwb/samples/tro£f.fonts 

/usr/lib/dwb/samples/troff .sizes 

/usr/lib/dwb/sbjl 

/usr/lib/dwb/sbj2 

/usr/Iib/dwb/sbj3 

/ usr/lib/dwb/sbjprep 

/usr/lib/dwb/stylel 

/ usr / lib / d wb /sty le2 

/usr/lib/dwb/style3 

/usr/lib/eign 

/usr/lib/font/devaps/B.add 

/usr / lib / f on t / de vaps / B.out 

/usr/lib/font/devaps/BLout 

/usr/lib/font/devaps/Cout 

/usr/lib/font/devaps/CE.out 

/ usr/lib/font/devaps/CI.out 

/usr/lib/font/devaps/CT.add 

/usr/lib/ f ont/devaps/CT.out 

/usr/lib/font/devaps/CW.add 

/usr/lib/foiit/devaps/CW«out 

/usr/lib/font/devaps/CX.add 

/usr/lib/font/devaps/CX.out 

/usr/lib/font/devaps/DESCout 

/usr/lib / f on t / de vaps / G.out 

/usr/lib/font/devaps/GB.add 

/usr/lib/font/devaps/GB.out 

/usr/lib/font/devaps/GI.add 

/ usr / lib / f ont /de vaps/ GLout 

/usr/lib/£ont/devaps/GR.add 

/usr/lib/font/devaps/GR.out 

/usr/lib/font/devaps/GS.add 

/usr/lib/font/devaps/GS.out 

/usr/lib/font/devaps/H.out 

/usr/lib/font/devaps/HB.out 

/usr/lib/font/devaps/HLadd 

/usr/lib/font/devaps/HLout 

/usr/lib/font/devaps/HK.add 

/usr/lib/font/devaps/HK.out 
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■.I 

/ usr / lib / font / de vaps/ HL.out 
/ usr / lib / f on t / de vaps / HM.out 
/ usr / lib / f bnt / de vaps / HX.add 
/ usr / lib / f on t / de vaps / HX.out 
/ usr / lib / f ont / de vaps / Ladd 
/ usr / lib / font / de vaps / Lout 
/usr/lib/font/devaps/MB.out 
/ usr / lib / font / de vaps / Ml.out 
/ usr / lib / f on t / devaps / MR.out 
/ usr / lib / font / devaps / MX.out 
/ usr / lib / f on t / devaps / P A.out 
/ usr / lib / font / devaps / PB.out 
/usr/lib/font/devaps/PLout 
/ usr / lib / f on t / devaps / PO.add 
/usr/lib/font/devaps/PO.out 
/usr/lib/font/devaps/PX.add 
/usr/lib/font/devaps/PX.out 
/ usr / lib / font / devaps/ R.add 
/ usr / lib / font / devaps / R.out 
/ usr / lib / font / devaps / S.add 
/ usr / lib / font / devaps / S.ou t 
/usr/lib/font/devaps/Sl.add 
/ usr / lib / f o n t / devaps / Sl-out 
/usr/lib/font/devaps/SCadd 
/ usr / lib / f on t / devaps / SCout 
/ usr / lib / f on t / devaps/ SM.add 
/usr/lib/font/devaps/SM.out 
/ usr / lib / font / devaps /TB.out 
/usr/lib/font/devaps/TX.add 
/usr/lib/font/devaps/TX.out 
/usr/lib/font/devaps/version 
/ usr / lib / font / de vilO / B.out 
/usr/lib/font/devilO/CW.out 
/usr/lib/font/devilO/DESCout 
/ usr / lib / f ont / de vilO / G.ou t 
/usr/lib/font/devilO/GLout 
/usr/lib/font/devilO/H.out 
/usr/lib/font/devilO/HB.out 
/usr/lib/font/devilO/HI.out 
/usr/lib/font/devilO/HK.out 
/usr/lib/font/devilO/HM.out 
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/usr/lib/font/devilO/Lout 

/usr/lib/font/devilO/PA.out 

/usr/lib/font/devilO/PB.out 

/usr/lib/font/devilO/PLout 

/usr/lib/font/devilO/PO.out 

/usr/lib/font/devilO/R.out 

/u8r/lib/font/devilO/S.out 

/usr/lib/font/devilO/ra8tilO/B.10 

/usr/lib/font/devilO/rastilO/B.12 

/usr/lib/font/devilO/rastilO/B.14 

/usr/lib/font/devilO/rastilO/B.16 

/usr/lib/font/devilO/rastilO/B.6 

/usr/lib/font/devilO/rastilO/B*8 

/usr/lib/font/devilO/rastilO/B.9 

/usr/lib/font/devilO/rastilO/BLlO 

/usr/lib/font/devilO/rastilO/BL12 

/usr/lib/foiit/devilO/rastilO/BL6 

/usr/lib/£ont/devilO/rastilO/BL8 

/usr/lib/font/devilO/rastilO/CW.lO 

/usr/lib/font/devilO/rastilO/CW.ll 

/usr/lib/£ont/devilO/rastilO/CW.12 

/usr/lib/.font/devilO/rastilO/CW.16 

/usr/lib/font/devilO/rastilO/CW.6 

/usr/lib/font/devilO/rastilO/CW.8 

/usr/lib/font/devilO/rastilO/CW.9 

/usr/lib/font/devilO/rastilO/H.lO 

/usr/lib/£ont/devilO/rastilO/H.12 

/usr/lib/font/devilO/rastilO/H,14 

/usr/lib/foiit/devilO/rastilO/H.16 

/usr/lib/font/devilO/rastilO/HJS 

/usr/lib/font/devilO/rastilO/H.6 

/usr/lib/£ont/devilO/rastilO/H.8 

/usr/lib/£ont/devilO/rastilO/H.9 

/usr/lib/£ont/devilO/rastilO/HB.10 

/usr/lib/£ont/devilO/rastilO/HB.14 

/usr/lib/£ont/devilO/rastilO/HB.9 

/usr/lib/£ont/devilO/rastilO/HI.10 

/usr/lib/£ont/devilO/rastilO/HL12 

/usr/lib/£ont/devilO/rastilO/HL14 

/usr/lib/font/devilO/rastilO/HL16 

/usr/lib/£ont/devilO/rastilO/HL18 
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/usr/lib/font/devilO/rastilO/HI.6 

/usr/lib/font/devilO/rastilO/HL8 

/usr/lib/font/devilO/rastilO/HL9 

/usr/lib/font/devilO/rastilO/HK.10 

/usr/lib/font/devilO/rastilO/HK.12 

/usr/lib/font/devilO/rastilO/HK.14 

/usr/lib/font/devilO/rastilO/HK.16 

/usr/lib/£ont/devilO/rastilO/HK.18 

/usr/lib/£ont/devilO/rastilO/HK.6 

/usr/lib/font/devilO/rastilO/HK.8 

/usr/lib/foiit/devilO/rastilO/HK.9 

/usr/lib/font/devilO/rastilO/LlO 

/usr/lib/font/devilO/rastilO/L12 

/usr/lib/£ont/devilO/rastilO/L14 

/usr/lib/font/devilO/rastilO/L16 

/usr/lib/font/devilO/rastilO/L6 

/usr/lib/font/devilO/rastilO/LS 

/usr/lib/font/devilO/rastilO/L9 

/usr/lib/font/devilO/rastilO/PA.lO 

/usr/lib/font/devilO/rastilO/PA.12 

/usr/lib/£ont/devilO/rastilO/PA.14 

/usr/Iib/font/devilO/rastilO/PA,6 

/usr/lib/font/devilO/rastilO/PA.S 

/usr/lib/£ont/devilO/rastilO/PB.10 

/usr/lib/font/devilO/rastilO/PB.12 

/usr/lib/font/devilO/rastilO/PB.14 

/usr/lib/font/devilO/rastilO/PB.6 

/usr/lib/font/devilO/rastilO/PB.S 

/usr/lib/font/devilO/rastilO/PLlO 

/usr/lib/font/devilO/rastilO/PL12 

/usr/lib/font/devilO/rastilO/PL14 

/usr/lib/font/devilO/rastilO/PL6 

/usr/lib/font/devilO/rastilO/PLS 

/usr/lib/font/devilO/rastilO/PO.lO 

/usr/lib/font/devilO/rastilO/PO.ll 

/usr/lib/fonl/devil0/rastil0/PO.12 

/usr/lib/font/devilO/rastilO/PO,16 

/usr/lib/font/devilO/rastilO/PO.e 

/usr/lib/font/devilO/rastilO/PO.8 

/usr/lib/font/devilO/rastilO/PO,9 

/usr/lib/font/devilO/rastilO/PX,10 
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/usr/lib/font/devilO/rastflO/PX.12 

/usr/lib/font/devilO/rastilO/PX.6 

/usr/lib/font/devilO/rastilO/PX.8 

/usr/lib/font/devilO/rastilO/R-lO 

/usr/lib/font/devilO/rastilO/R.12 

/usr/lib/font/devilO/rastilO/R.14 

/usr/lib/font/devilO/rastilO/R.16 

/usr/lib/font/devilO/rastilO/R.6 

/usr/lib/font/devilO/rastilO/R.8 

/usr/lib/£ont/devilO/rastilO/R.9 

/usr/lib/font/devilO/rastilO/RASTERLIST 

/usr/lib/font/devilO/rastilO/S.lO 

/usr/lib/font/devilO/rastilO/S.12 

/usr/lib/font/devilO/rastilO/S.14 

/usr/lib/font/devilO/rastilO/S-16 

/usr/lib/font/devilO/rastilO/S.18 

/usr/lib/font/devilO/rastilO/S.24 

/usr/lib/font/devilO/rastilO/S.6 

/usr/lib/font/devilO/rastilO/S.8 

/usr/Ub/font/devilO/rastilO/S.9 

/usr/lib/font/devilO/rastilO/devaps/B.out 

/usr/lib/font/devilO/rastilO/devaps/BI.out 

/usr/lib/font/devilO/rastilO/devaps/Cout 

/usr/lib/font/devilO/rastilO/devaps/CE.out 

/usr/lib/font/devilO/rastilO/devaps/CI.out 

/usr/lib/font/devilO/rastilO/devaps/CT.out 

/usr/lib/font/devilO/rastilO/devaps/CW.out 

/usr/lib/font/devilO/rastilO/devaps/CX.out 

/usr/lib/font/devilO/rastilO/devaps/DESC.out 

/usr/lil>/font/devilO/rastilO/devaps/G.out 

/usr/lib/font/devilO/rastilO/devaps/GB.out 

/usr/lib/font/devilO/rastilO/devaps/GLout 

/usr/lib/font/devilO/rastilO/devaps/GR.out 

/usr/lib/font/devilO/rastilO/devaps/GS.out 

/usr/lib/font/devilO/rastilO/devaps/H.out 

/usr/lib/font/devilO/rastilO/devaps/HB.out 

/ usr / lib / f on t / dcvilO / rastilO / devaps / HLout 

/usr/lib/font/devilO/rastilO/devaps/HK.out 

/usr/lib/font/devilO/rastilO/devaps/HL.out 

/usr/lib/font/devilO/rastilO/devaps/HM.out 

/ usr / lib / font / devilO / rastilO / devaps / HX.out 
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/usr/lib/font/devilO 
/usr/lib/font/devilO 
/ usr / lib / font / de vilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/font/devilO 
/usr/lib/ macros/an 
/ usr / lib / macros / mmn 
/ usr/lib / macros/ mmt 
/usr/lib / macros/ ptx 
/ usr/lib/macros/strings.mm 
/ usr / lib / macros / vmca 



/ rastilO/ devaps/Lout 
/ rastilO /de vaps / MB.out 
/ rastilO / de vaps / Ml.out 
/ rastilO /de vaps / MR.out 
/ rastilO / de vaps / MX.out 
/rastilO / de vaps / PA.out 
/ rastilO/ de vaps / PB.out 
/ rastilO/devaps/PLout 
/ rastilO/ devaps / PO.ou t 
/rastilO/devaps/PX.out 
/ rastilO/ devaps/ R.out 
/ rastilO/devaps/S.out 
/ rastilO / devaps /Sl.out 
/ rastilO / devaps /SC.out 
/ rastilO / devaps /SM.out 
/rastilO/devaps/TB.out 
/rastilO/devaps/TX.out 



/usr/lib/nterm 
/ usr/ lib /n term 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 
/usr/lib/nterm 



/tab.2631 
/tab.2631-c 
/tab.2631.e 
/tab.300 
/tab.300-12 
/tab.300S 
/tab.300S-12 
/tab.300s 
/tab300s-12 
/tab.37 
/tab.382 
/tab.4000A 
/tab.4000a 
/tab.450 
/tab.450-12 
/tab.832 
/tab.8510 
/tab.X 
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/ usr / lib / n term / tab Jp 
/usr/lib/nterin/tab.tn300 
/ usr / lib / 1 mac / tmac.an 
/ usr / lib / 1 mac / tmac.m 
/ usr / lib / 1 mac / tmac.p tx 
/ usr / lib / tmac / tmac* v 
/ usr / pub / apseqnchar 
/ usr / pub / ca teqnchar 
/ usr / pub /eqnchar 
/ usr / pub / terminals 
/usr/lib/ readme/ dwb 
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Appendix 4: Converting Terminai Description 
Fiies to ASCii Format 



The terminal description files for nroff contained in /usr/lib/nterm 
were compiled C language object code in Release 1.0 and earlier and have 
been converted to ASCII files in Release 2.0. Any user-defined terminal 
description files will need to be converted to ASCII format as well. Conver- 
sion of a user-defined file should involve minor modifications to the C 
source file. 

The following list describes the terminal tables for nroff. (In the 
description, Vhite space" means any combination of spaces, tabs, and new- 
lines). 

■ The first line should contain the name of the terminal (a 
string with no embedded white space). 

■ The terminal name is followed by a table of 25 lines (defining 
the first 25 items in struct t, laid out in file nroff.d/tw.h), as 
shown below. 



bset 



[integer]/ *bits that must be set for printing*/ 
[integer]/ *bits that must be reset for printing*/ 
[integer]/ *size of unit of horizontal motion*/ 
[integer]/ *size of unit of vertical motion*/ 
[integer]/ *size of line of vertical motion*/ 
[integer]/ *size of character horizontally*/ 
[integer]/ *size of Em of horizontal motion*/ 
[integer]/ *size of half line of vertical motion*/ 
[integer]/ *horizontal resolution* / 
[string]/ *sequence to initialize terminal*/ 
[string] /*sequence to restore terminal*/ 
[string]/ *sequence to print newline*/ 



breset 



Hor 



Vert 



Newline 



Char 



Em 



Halfline 



Adj 



twinit 



twrest 



twnl 



RELEASE NOTES 49 



Appendix 4 



hlr [string]/ *sequence for half-line reverse*/ 

hlf [string]/ *sequence for half-line forward*/ 

fir [string]/ *sequence for full-line reverse*/ 

bdon [string]/ *sequence to turn on bold*/ 

bdoff [string]/ *sequence to turn off bold*/ 

iton [string]/ *sequence to turn on italic*/ 

itoff [string]/ *sequence to turn off italic*/ 

ploton [string]/ *sequence to enter plot mode*/ 

plotoff [string]/* sequence to leave plot mode*/ 

up [string]/ *sequence to move up 1 space in plot 

mode*/ 

down [string]/ *sequence to move down 1 space in plot 
mode*/ 

right [string]/ *sequence to move right 1 space in plot 
mode*/ 

left [string]/ *sequence to move left 1 space in plot 

mode*/ 

■ This table is fixed format, and the order cannot be changed. 
Entries should be on separate lines, and they should contain 
exactly two fields (the comment should be omitted) separated by 
white space. The first field is the string identifying the value 
(this is not verified). The second field is the value. The value is 
either an integer, or a string, as specified above. An integer is a 
sequence of digits. Integers describing sizes are expressed in 
units of 1/240 of an inch. A string is a sequence of characters 
(surrounded by quotes). For non-printable ASCII characters the 
following escapes hold as in C: \b, \t, \n, \rV \"/ and | followed 
by three octal digits. 

■ This is followed by a line containing the word "charset," and 
then by the table of special characters (all the non-ASCII charac- 
ters that nroff /troff knows by two-character names, for example, 
\(hy and \(ga). The entries in this table can be in any order, and 
the entries should be restricted to only those characters that can 
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be printed on the terminal in question. The format of each line 
(defining one special character) is: the (two-character) name of 
the special character, followed by white space, followed by the 
width of the character (in ems), followed by white space, fol- 
lowed by the sequence needed to produce the character. This 
sequence may be surrounded by quotes. The same escapes hold 
as for strings above. 

The best way to create a terminal table for a device is to take a terminal 
table for an existing device and modify it. Terminal tables files are found in 
/usr/lib/nterm. 
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The following notes may help you avoid problems or to troubleshoot 
when problems do occur. 

■ The checkmm command will flag some business letter macros as 
possible errors, even though a file containing the letter macros 
will format properly. 

■ The checkmm command will flag as possible errors the macros 
that produce labeled footnotes, if they occur inside lists. A file 
containing such a sequence of macros will format properly, 
however. 

■ The chapter "The Preprocessor eqn" in the User's Guide suggests 
running the eqn preprocessor on the 

/usr/lib/dwb/samples/eqn.stats file. If you do this you will 
get the following warning: 

eqn vazmng: tmquoted troff oonmand 

The file eqn.stats will format properly, however. 

■ A README file is supplied with the binary version of the 
DOCUMENTER'S WORKBENCH Software for the 3B5 Computer 
and the 3B2 Computer. This file incorrectly states that there are 
only three macro packages included in the package, although it 
correctly names the four packages that are included: mm^ mv, 
mptX/ and man. 

■ Use of the mv macro package inhibits true constant width spac- 
ing in the output text. If you need to show constant width spac- 
ing in a viewgraph you can simulate it by entering the troff 
request 

.ss 12 

before the text you want to appear in constant width spacing. 
From that point, standard troff inter-word spacing will be used. 
You can restore the standard mv inter-word spacing by entering 
the request 

•ss 16 

at the point you want it to resume. 



52 RELEASE NOTES 




,e Pre 




and UNIX"' Systems 




• The C Programmer's Handbook Bell Labs/M. i. Doisky 

• The UNIX System User's Handbook Bell Labs/M, r Boisky 

• The Vi User's Handbook Bell Labs/M. L Boisky 

• UNIX System Software Readings at&t unix pacific 

• UNIX System Readings and Applications, Volume I Bell Labs 

• UNIX System Readings and Applications, Volume II Beii Labs 

• UNIX System V Utilities Release Notes at&t 

• UNIX System V Streams Primer at&t 

• UNIX System V User's Guide, Second Edition at&t 

• UNIX System V User's Reference Manual at&t 

• UNIX System V Programmer's Reference Manual atbt 

• UNIX System V Streams Programmers Guide atst 

• UNIX System V Network Programmer's Guide at&t 

• UNIX System V Programmer's Guide at&t 

• UNIX System V Documentor's Workbench Users Guide at&t 

• UNIX System V Documentor's Workbench Reference Manual at&t 



PRENTICE-HALL, INC., Englewood Cliffs, N.J. 07632 



ISBN □-13"^43SaO-a 



